[asterisk-dev] CHANGES and UPGRADE.txt

[Ben Ford]

Hey everyone,

Recently we’ve made some changes to how we handle additions to the CHANGES
and UPGRADE.txt files. The reasoning behind this is that whenever more than
one person needed to change one of these files (not uncommon), you would
almost certainly run into merge conflicts. This gets pretty stale after a
while. Now, instead of adding changes to these files directly, we’ve added
two new directories: doc/CHANGES-staging and doc/UPGRADE-staging. Changes
to CHANGES and UPGRADE.txt will go into these directories, respectively.
The goal of this is to prevent as many merge conflicts as possible. The
release process will now be responsible for merging these changes into the
appropriate files.

Whenever you make a change that requires an addition to these directories,
just create a new .txt file and name it something relevant to the changes
you have made. These files MUST be .txt files. These files also have a
special format that they follow when being parsed by the release script.
The first line should contain the subject of your change. Right now, this
is the only mandatory header. The only optional header available is
Master-Only, which should only ever go in the master branch and can only
have a value of true or True. There should be a blank line separating the
headers from the message body below.

Let’s take a look at a change that went into master. Before, you would have
to do something like this in the CHANGES file:

 Channels

--------------------------

* The core no longer uses the stasis cache for channels snapshots.

  The following APIs are no longer available:

      ast_channel_topic_cached()

      ast_channel_topic_all_cached()

  The ast_channel_cache_all() and ast_channel_cache_by_name() functions

  now returns an ao2_container of ast_channel_snapshots rather than a

  container of stasis_messages therefore you can't call stasis_cache

  functions on it.

  The ast_channel_topic_all() function now returns a normal topic,

  not a cached one so you can't use stasis cache functions on it either.

  The ast_channel_snapshot_type() stasis message now has the

  ast_channel_snapshot_update structure as it's data.

  ast_channel_snapshot_get_latest() still returns the latest snapshot.

Now, this documentation should go in the doc/CHANGES-staging directory. A
good name for this could be something like channels_stasis_cache.txt. The
file name tells us what the change is generally about. Inside of the file,
the above would translate to this:

  Subject: Channels

Master-Only: true

  The core no longer uses the stasis cache for channels snapshots.

  The following APIs are no longer available:

      ast_channel_topic_cached()

      ast_channel_topic_all_cached()

  The ast_channel_cache_all() and ast_channel_cache_by_name() functions

  now returns an ao2_container of ast_channel_snapshots rather than a

  container of stasis_messages therefore you can't call stasis_cache

  functions on it.

  The ast_channel_topic_all() function now returns a normal topic,

  not a cached one so you can't use stasis cache functions on it either.

  The ast_channel_snapshot_type() stasis message now has the

  ast_channel_snapshot_update structure as it's data.

  ast_channel_snapshot_get_latest() still returns the latest snapshot.

The Master-Only tag is necessary because this is a change that would not go
into any of the other mainline branches (13, 16). If the change were to go
in these other branches, you don’t need to add that tag at all. One other
cool thing you can do is have multiple subject headers. This way, if you
want to have the same message for two different subjects (not common, but
it could happen), you don't need to create another file with the same body
content; it can all be done in one file.

Another thing to note is that we no longer separate the UPGRADE.txt file
into multiple smaller files. Just like CHANGES, this will now be one file
that tracks all information for changes between versions.

That’s pretty much all there is to it! There is a README.md file in each of
the staging directories that has examples and information inside, so you
will always have something to refer to. We also have a wiki page
<https://wiki.asterisk.org/wiki/display/AST/CHANGES+and+UPGRADE.txt>
available! Check it out and leave comments there or post them here if you
have any questions.

-- 
*Benjamin Ford*
Digium - A Sangoma Company | Software Engineer
445 Jan Davis Drive NW - Huntsville, AL 35806 - US
<https://maps.google.com/?q=445+Jan+Davis+Drive+NW+-+Huntsville,+AL+35806+-+US&entry=gmail&source=g>
Check us out at: https://digium.com · https://sangoma.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20190416/d6da4e38/attachment-0001.html>