Up until early 2019, anyone contributing to Asterisk probably came across a change that required an addition to the CHANGES or UPGRADE.txt files. If you're one of those people, then you probably also know how frustrating it was having to deal with merge conflicts if another person had touched this file in one of their reviews. Because of this, a new process has been added that will ease the pains of having to document something in these files.
A couple of things. You no longer need to add anything to the CHANGES and UPGRADE.txt files themselves. By removing this, there should not be any merge conflicts (at least, none relating to these files!). Instead, two new directories have been created under the doc/ directory: CHANGES-staging and UPGRADE-staging. Any code you add that is considered a new feature or an enhancement of an existing feature should be documented in the CHANGES-staging directory. Changes that would break existing behavior should be documented under the UPGRADE-staging directory. The format is similar to how things were done in the past, but you no longer need to worry about typing out dashes and asterisks to separate things. That's all done for you!
The release process is what handles updating the CHANGES and UPGRADE.txt files now. Whenever a release is being made, everything in the staging directories is taken and added to the beginning of the corresponding file. Everything that has the same subject (e.g, "res_pjsip") will be grouped under one section and separated by asterisks, exactly how it has been done in the past. The directories will then be cleaned up and the commit will be pushed in along with everything else. Easy as that!
Here's an example of what one of these directories might look like before a release:
Inside of one of these files (say, the first one), it should follow the format of subject lines, headers, blank line, then a description of the change. It could look something like this:
Viola! That's all there is to it. One thing to note is that changes will be sorted alphabetically, and then sorted by commit timestamp (in epoch). The reasoning will be explained below.
Mainline Branches vs Master
Releases from mainline branches (16.2.0 -> 16.3.0) work as expected following the above rules. The changes are fetched from the staging directory, put in their individual categories, and then sorted. This is all fine until we get to master. Master does not get a release for 16.2.0 -> 16.3.0. Because of this, things need to be done a little differently. Ordinarily when a release was done, the changes would be cherry picked to the master CHANGES and UPGRADE.txt files as well, and upon doing a release of a new version of Asterisk from master, a new UPGRADE.txt file would be created. Now, there will only be one UPGRADE.txt file. When releasing 17, there will be 2 new sections added to the file: a "new in 17" section and a "changes from 16 to 17" section. CHANGES will behave in a similar way.
Changes that are master-only need a special header to denote them as such. This won't cause any weird issues with cherry-picking either, since the changes will only be going into the master branch. You will need to add "Master-Only" under the "Subject:" header, like so:
These changes will be separated into a different storage structure and added BEFORE the other changes, so that the new stuff is seen first!
Running it Manually
Sometimes, it may be necessary to make these changes manually. Master is one such example, since the mainline branch will never be "master". There could also be a scenario where the branch to be released is already in existence, in which case you would need to run the script on this branch (for example, if releasing 16.3.0, this branch would need to be updated; 16 would get updated during the mkrelease script). Luckily, all you have to do is run a couple of scripts to accomplish this:
process-staging-changes script will take all files in the doc/CHANGES-staging and doc/UPGRADE-staging directories, add their contents to the CHANGES and UPGRADE.txt files, and then remove those files.
commit-staging-changes script will commit ALL changes in the working directory with the commit message "Update CHANGES and UPGRADE.txt for <version>".