[Asterisk-code-review] build: Improve handling of CHANGES and UPGRADE.txt for releases. (...repotools[master])

[Benjamin Keith Ford]

Hello Kevin Harwell, George Joseph, 

I'd like you to reexamine a change. Please visit

    https://gerrit.asterisk.org/c/repotools/+/10941

to look at the new patch set (#7).

Change subject: build: Improve handling of CHANGES and UPGRADE.txt for releases.
......................................................................

build: Improve handling of CHANGES and UPGRADE.txt for releases.

The release script now handles the merging of the CHANGES and
UPGRADE.txt files for us! When a release is being done, the script will
go through the staging changes in the Asterisk working directory
(<asterisk-home>/doc/<file>-staging) and add each change to the
corresponding file. A separate script (process-staging-changes) has also
been added that can be used when creating a new version from master. It
takes 3 arguments: -l/--local-root, which is optional,
-s/--start-version, and -e/--end-version. You can use -h for more
information on each option. Another script has been added that should be
run after process-staging-changes. This script is called
commit-staging-changes. It will go through all unstaged changes, add
them, and then commit them to the local repository. Then it will push
these changes to the remote. These scripts should be used for master or
if we need to do things manually (for some reason).

This means that there's a new way to document our major changes. All
changes for CHANGES will go into doc/CHANGES-staging and all changes for
UPGRADE.txt will go into doc/UPGRADE-staging. Each of these files should
have a meaningful name related to what the change is. For example, if
you made a change to something in pjsip, your file might be called
"res_pjsip_relative_title", where "relative_title" will be something a
little more descriptive than that. Inside of each file, you will have a
subject line followed by a blank line, with the description of the
change following that. You can have multiple subject lines in one file.
For example, it may look something like this:

   Subject: res_pjsip

   This is a detailed description of what I changed.

   You can have new lines in between as well, spacing is handled by the
   release script!

   Subject: res_pjsip

   You can have another subject as well!

   Subject: Core

   The subjects don't have to be the same either!

The header lines (Subject:) are case sensative. One thing to note is
that master is different. Since changes that are master-only will only
go into the master branch, we add another special tag (Master-Only) that
will go underneath the "Subject:" header. There should be no space
between these.

   Subject: res_ari
   Master-Only: true

   This is a master-only change!

   Subject: app_bridge
   Master-Only: True

   You can put "true" or "True", it's fine either way!

Note that the "Master-Only" header will only ever be true. There should
not be any scenarios where there will be a "Master-Only" header with the
value false.

For master (and possibly other releases), it will be necessary to do
some of this manually before running the mkrelease.py script. This is
because when cutting a major release (like from 16 to 17), the mainline
branch will never be master, so master must have these changes made
manually. The easiest way to do this is to make the changes before
cutting the new branch, so that the work does not need to be done twice.
Here's an example (run from the repotools dir):

   ./process-staging-changes -s 16 -e 17
   (check the working dir to make sure it looks correct)
   ./commit-staging-changes -v 17

Note that both of these scripts take an optional parameter (-l /
--local-root). This works the exact same way as in the mkrelease.py
script. If you are not working from the default directory (/tmp), you
MUST specify the path with this option.

Fore more information, check out the wiki page:
https://wiki.asterisk.org/wiki/display/AST/CHANGES+and+UPGRADE.txt

First step for ASTERISK_28111. The directories will need to be added,
and all changes will need to be refactored into these directories. Also,
the UPGRADE.txt file will no longer branch off into different files for
each release of a new major version, so these should be merged together
as well to reduce clutter.

Change-Id: I6dc084afedaeecaf36aaec66c3cf6a5a8ed4ef3c
---
A commit-staging-changes
M digium_git.py
M mkrelease.py
A process-staging-changes
A staging_changes.py
5 files changed, 429 insertions(+), 6 deletions(-)


  git pull ssh://gerrit.asterisk.org:29418/repotools refs/changes/41/10941/7
-- 
To view, visit https://gerrit.asterisk.org/c/repotools/+/10941
To unsubscribe, or for help writing mail filters, visit https://gerrit.asterisk.org/settings

Gerrit-Project: repotools
Gerrit-Branch: master
Gerrit-Change-Id: I6dc084afedaeecaf36aaec66c3cf6a5a8ed4ef3c
Gerrit-Change-Number: 10941
Gerrit-PatchSet: 7
Gerrit-Owner: Benjamin Keith Ford <bford at digium.com>
Gerrit-Reviewer: Benjamin Keith Ford <bford at digium.com>
Gerrit-Reviewer: George Joseph <gjoseph at digium.com>
Gerrit-Reviewer: Kevin Harwell <kharwell at digium.com>
Gerrit-MessageType: newpatchset
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20190401/435d609a/attachment-0001.html>