Skip to end of metadata
Go to start of metadata

Overview

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. These directories will then be cleaned up and the commit will be pushed in along with everything else. Easy as that!

Icon

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.

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:

Viola! That's all there is to it.

  • No labels

5 Comments

  1. A few questions...

    What do we do about the "master" branch since we never actually create a release from it?

    Do we need to use a file naming scheme that forces an order like "0001-somechange"?

    Should we use headers in the file like "Subject: "?  This would allow us to add other metadata to the files as well if needed in the future?

     

    1. Do we need to use a file naming scheme that forces an order like "0001-somechange"?

      Offhand I can't think of a use case where ordering matters. Also having a number like this at the start could potentially cause collisions with reviews (unlikely and not a big deal if it happens, but still a remote chance)

      Should we use headers in the file like "Subject: "?  This would allow us to add other metadata to the files as well if needed in the future?

      +1 to this. Not only does it give more flexibility, but it documents what is what.

      1. What do we do about the "master" branch since we never actually create a release from it?

        That's a very good question. I guess we just cut and push out the branch for that? I'm actually unsure on the process myself. There could be another script added to repotools (or swdev, or whatever) that pulls from the same extracting class and does the changes for us, but that would require a manual action if I'm understanding this correctly. It would be more "automated" and easy than what we have now, that's for sure.

        Offhand I can't think of a use case where ordering matters. Also having a number like this at the start could potentially cause collisions with reviews (unlikely and not a big deal if it happens, but still a remote chance)

        I agree with this, ordering won't be a big deal since all the changes will just be listed in "from this version to this version", so as long as they are all under the same thing, this shouldn't be an issue.

        Should we use headers in the file like "Subject: "?  This would allow us to add other metadata to the files as well if needed in the future?

        This is a good point. Should be an easy change.

    2. What do we do about the "master" branch since we never actually create a release from it?

      I think "master" should be processed before creating each mainline branch.  So process the CHANGES and UPGRADE.txt on master before branching '17'.

      Do we need to use a file naming scheme that forces an order like "0001-somechange"?

      We could use numbers to be used to group by importance.  So 0001-major would be listed before 0100-minor, 1000-trivial.  We should agree upon a number of digits.  As an alternative we could use headers for sorting, maybe group by an 'Importance:' header and sort by 'Subject:'.

      Should we use headers in the file like "Subject: "?  This would allow us to add other metadata to the files as well if needed in the future?

      Absolutely.  This would allow future expansion of release related commands.  For example 'AMI: <type>' to cause a certain type of bump to the AMI version (to be handled differently for major releases obviously).  Require that file follow basic HTTP format (require file to start with one header per line, blank line between headers and body).

      1. I think "master" should be processed before creating each mainline branch.  So process the CHANGES and UPGRADE.txt on master before branching '17'.

        Yep, this could be done as a standalone (not part of release process), so someone would need to run the script on master to fetch all the changes before cutting the master branch.

        We could use numbers to be used to group by importance.  So 0001-major would be listed before 0100-minor, 1000-trivial.  We should agree upon a number of digits.  As an alternative we could use headers for sorting, maybe group by an 'Importance:' header and sort by 'Subject:'.

        This is definitely an option. We could have priorities / importance / impact, whatever you want to call the option, and have that as another header, like the subject line. So long as the subject line is the first line, we can add any number of additional options underneath to further itemize changes. I think that the names of the files should not rely on any kind numbering though - this can all be done within the files themselves, and will allow each individual subject / change to be categorized by importance.