Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Next »


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.

What Changed?

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!


During the release process, if something goes wrong, the working directory that the release is being done from may need to be reset. You may be able to just do a

on the working directory, but do double check and make sure everything looks the way you would expect it to. There's a chance you may need to reset the HEAD, so check commit history as well!

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 line, blank line, then a description of the change. It could look something like this:


The "Subject: res_pjsip" line is considered a special header and is case sensitive. This is what the script uses to determine what goes where and what content belongs to. Other headers can be added in the future this way, following the subject header.

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:


Both of these scripts take an optional parameter (-l / --local-root). This works the same way as in the mkrelease script. If you're using a directory that's not the default (/tmp), you MUST specify this the path with this option.

The 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.

The commit-staging-changes script will commit ALL changes in the working directory with the commit message "Update CHANGES and UPGRADE.txt for <version>".

  • No labels