build: Add staging directories for future changes.
authorBen Ford <bford@digium.com>
Wed, 27 Mar 2019 16:03:40 +0000 (11:03 -0500)
committerBenjamin Keith Ford <bford@digium.com>
Wed, 27 Mar 2019 18:32:54 +0000 (12:32 -0600)
This is the first step in changing the release process so that changes
made to the CHANGES and UPGRADE.txt files do not result in merge
conflicts every time multiple people modify these files. The changes
made will go in these new directories: doc/CHANGES-staging and
doc/UPGRADE-staging. The README.md files explain how things will work,
but here's a little overview. When you make a change that would go in
either CHANGES or UPGRADE.txt, this should instead be documented in a
new file in the doc/CHANGES-staging or doc/UPGRADE-staging directory,
respectively. The format will look like this:

   Subject: res_pjsip

   A description that explains the changes made and why. The release
   script will handle the bulleting and section separators! The
   'Subject:' header is case-sensitive.

   You can still separate with new lines within your description.

   Subject: res_ari
   Master-Only: true

   You can have more than one subject, and they don't have to be the
   same! Also, the 'Master-Only' header should always be true and is
   also case-sensitive (but the value is not - you can have 'true' or
   'True'). This header will only ever be present in the master branch.

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

This is an initial change for ASTERISK_28111. Functionally, this will
make no difference, but it will prep the directories for when the
changes from CHANGES and UPGRADE.txt are extracted.

Change-Id: I8d852f284f66ac456b26dcb899ee46babf7d15b6

doc/CHANGES-staging/README.md [new file with mode: 0644]
doc/UPGRADE-staging/README.md [new file with mode: 0644]

diff --git a/doc/CHANGES-staging/README.md b/doc/CHANGES-staging/README.md
new file mode 100644 (file)
index 0000000..da0df2a
--- /dev/null
@@ -0,0 +1,33 @@
+## **DO NOT REMOVE THIS FILE!**
+
+The only files that should be added to this directory are ones that will be
+used by the release script to update the CHANGES file automatically. The only
+time that it is necessary to add something to the CHANGES-staging directory is
+if you are either adding a new feature to Asterisk or adding new functionality
+to an existing feature. The file does not need to have a meaningful name, but
+it probably should. If there are multiple items that need documenting, each can
+be separated with a subject line, which should always start with "Subject:",
+followed by the subject of the change. This is case sensitive! For example, if
+you are making a change to PJSIP, then you might add the file
+"res_pjsip_my_cool_feature" to this directory, with a short description of what
+it does. If you are adding multiple entries, they should be done in the same
+commit to avoid merge conflicts. Here's an example:
+
+> Subject: res_pjsip
+>
+> Here's a pretty good description of my new feature that explains exactly what
+> it does and how to use it.
+>
+> Subject: core
+> Master-Only: true
+>
+> Here's another description of something else I added that is a big enough
+> change to warrant another entry in the CHANGES file.
+
+Note that the second subject has another header: "Master-Only". Changes that go
+into the master branch and ONLY the master branch are the only ones that should
+have this header. Also, the value can only be "true" or "True". The
+"Master-Only" part of the header IS case-sensitive, however!
+
+For more information, check out the wiki page:
+https://wiki.asterisk.org/wiki/display/AST/CHANGES+and+UPGRADE.txt
diff --git a/doc/UPGRADE-staging/README.md b/doc/UPGRADE-staging/README.md
new file mode 100644 (file)
index 0000000..1ef9334
--- /dev/null
@@ -0,0 +1,32 @@
+## **DO NOT REMOVE THIS FILE!**
+
+The only files that should be added to this directory are ones that will be
+used by the release script to update the UPGRADE.txt file automatically. The
+only time that it is necessary to add something to the UPGRADE-staging directory
+is if you are making a breaking change to an existing feature in Asterisk. The
+file does not need to have a meaningful name, but it probably should. If there
+are multiple items that need documenting, each can be separated with a subject
+line, which should always start with "Subject:", followed by the subject of the
+change. This is case sensitive! For example, if you are making a change to PJSIP,
+then you might add the file "res_pjsip_breaking_change" to this directory, with
+a short description of what it does. If you are adding multiple entries, they
+should be done in the same commit to avoid merge conflicts. Here's an example:
+
+> Subject: res_pjsip
+>
+> Here's a pretty good description of what I changed that explains exactly what
+> it does and why it breaks things (and why they needed to be broken).
+>
+> Subject: core
+> Master-Only: true
+>
+> Here's another description of something else I added that is a big enough
+> change to warrant another entry in the UPDATE.txt file.
+
+Note that the second subject has another header: "Master-Only". Changes that go
+into the master branch and ONLY the master branch are the only ones that should
+have this header. Also, the value can only be "true" or "True". The
+"Master-Only" part of the header IS case-sensitive, however!
+
+For more information, check out the wiki page:
+https://wiki.asterisk.org/wiki/display/AST/CHANGES+and+UPGRADE.txt