During development cycle we put various notes for developers in various upgrade.txt
They are not well organised, there are many locations and it becomes confusing for plugin developers where to look for information.
For 3.3 everything was summarized here: https://docs.moodle.org/dev/Moodle_3.3_release_notes#Upgrading_plugins

Let's once and forever agree on what goes in upgrade.txt, which files to use and refer to this policy in the future.

Question 1. Which upgrade.txt to use?

What we have currently:
1. Notes about changes in core APIs, deprecations, etc. go to lib/upgrade.txt
2. Notes about changes in some core APIs, however, go to their personal upgrade.txt, for example, tag/upgrade.txt, media/upgrade.txt, cache/upgrade.txt and even admin/upgrade.txt
3. Notes about changes in individual plugin types go to the parent directory of this plugin type, for example: question/type/upgrade.txt , course/format/upgrade.txt , mod/upgrade.txt , etc.
4. Notes about changes in individual plugins go to the upgrade.txt in this plugin, for example mod/forum/upgrade.txt , admin/tool/behat/upgrade.txt , etc.

Notes in #1 should be read by all plugin devs during upgrade. Notes in #2 should be read by almost all plugins devs during upgrade if they remember to do it. Notes in #3 should be read by devs of plugins of this type. Notes in #4 should be read by devs of plugins that depend on this plugin or use its methods.

Question 2. Format in lib/db/upgrade.txt

Currently we use a list that becomes several pages long by the time of release, it is not sorted, not categories and hard to read.

Question 3. What exactly should we mention in upgrade.txt

I think this is clear - only notes to developers, no information for admins, teachers or students should go here.

Deprecations, API changes and new features are all mixed together in this list. Perhaps we can discuss how to distinguish them.