Changing CHANGES (and UPGRADE.txt)

Overview

For those of you who have been around for a while now and contribute to the code base, you probably know about CHANGES and UPGRADE.txt and how annoying it can be when multiple people have made modifications to these files at the same time. For those of you who don’t know what I’m talking about, here’s a little background. We have a couple of files that are maintained by developers, documenting changes and new features that go into Asterisk. In CHANGES, you will find information on new features, small changes to existing code, and so on. In UPGRADE.txt, you will find information on breaking changes to Asterisk that you should be aware of before upgrading to a new version. “Breaking changes” sounds scarier than it is. What I mean by this are changes that may cause things to not work the same way as they did in a previous version. You might be wondering, “Why in the world would you want to do that?” We always have a good reason behind the changes we make, and more often than not, it’s because something is too difficult to maintain the way it is, or the current implementation could be made better, more efficient.

The problem is not the files themselves; it’s how we make changes to the files. If Alice and Bob both make some changes to Asterisk and document them in CHANGES, you will most likely have a merge conflict if they modified the same part of the file. Merge conflicts are annoying and can be easily eliminated in situations like this. That’s why we’ve decided to make some changes to how we add documentation to these files.

The Process

Let’s talk about what all goes into adding an entry to CHANGES or UPGRADE.txt. Say you’ve made a change to PJSIP, adding a cool new feature that you want to share with the community. First you would need to look at the CHANGES file and go to the appropriate version your change would be introduced in. For example, maybe your change is going into 13.27.0. You would look for the “Functionality changes from Asterisk 13.26.0 to Asterisk 13.27.0” section. Next, you would need to see if there is a category that already exists for your change. In this case, you would probably look for something like “res_pjsip”. Then, you can add information on your change similar to other entries in the file. If any of these things don’t exist, you would need to add them yourself. Here’s an example of what it might look like:

------------------------------------------------------------------------------
--- Functionality changes from Asterisk 13.26.0 to Asterisk 13.27.0 ----------
------------------------------------------------------------------------------

res_pjsip
------------------
 * A detailed description of what I did and the cool new features that got
   added. Your description should be much better than this.

This works, but like I mentioned earlier, what if someone else modifies the same area of the file as you? What if you both add some cool stuff to PJSIP, and both of you have to add a category for it? That’s what we wanted to fix. Our solution for this was adding two new directories: doc/CHANGES-staging and doc/UPGRADE-staging. Changes for CHANGES and UPGRADE.txt will go into these directories, respectively. Each change will be represented as a .txt file. These files should have meaningful names that reflect what the change is about. For example, let’s say you made a change to voicemail that would send you a text message whenever a voicemail was received. You might name the file app_voicemail_text_message_notify.txt. Inside of the file, the format is a little more specific. You will need a subject header (you can have more than one; more on this later) that contains the category name. If this is a change that will only go into the master branch, you will need to add the “Master-Only” header, which can only have a value of “true” (or “True”). These headers will go at the beginning of the file, followed by a blank line. After that, you can put the description of your change. Here’s what the file would look like:

Subject: app_voicemail
Master-Only: true

Added the ability to receive text message notifications whenever a voicemail
is received.

This would still need a better description, but you get the idea. Each change made will follow this format. If this was an actual change going into Asterisk, it would probably affect more than just app_voicemail. This is where multiple subject headers can come in handy. If you wanted to have this description show up under another header as well as “app_voicemail”, just add another subject header. The description will be copied to each category you have a subject header for; no need for another file!

How Does This Translate to CHANGES and UPGRADE.txt?

You might be wondering what happens to these files and how the changes are actually added to their corresponding files. Now, all of this is done for us during the release process. Whenever we release a new version of Asterisk, the script will automatically go through the staging directories and process all of the files inside. For each change, the script will parse the file, add the information to the appropriate categories, and add it to the top of the file. Each change is sorted alphabetically first, then by commit timestamp. This way, it should be much easier to find the changes that are relevant to you, and master will retain a better history once a new major version of Asterisk is released.

Check out the wiki page here! Also, there are README.md files that can be found in either of the staging directories. All future commits to Asterisk must follow this format. Merge conflicts over CHANGES and UPGRADE.txt are a thing of the past.

Leave a Reply

Your email address will not be published. Required fields are marked *


The reCAPTCHA verification period has expired. Please reload the page.

About the Author

What can we help you find?