build: Revise CHANGES and UPGRADE.txt handling.

This changes the way that we handle adding changes to CHANGES and
UPGRADE.txt. The reason for this is because whenever someone needed to
make a change to one of these files and someone else had already done
so, you would run into merge conflicts. With this new setup, there will
never be merge conflicts since all changes will be documented in the
doc/<file>-staging directory. The release script is now responsible for
merging all of these changes into the appropriate files.

There is a special format that these files have to follow in order to be
parsed. The files do not need to have a meaningful name, but it is
strongly recommended. For example, if you made a change to pjsip, you
may have something like this "res_pjsip_relative_title", where
"relative_title" is something more descriptive than that. Inside each
file, you will need a subject line for your change, followed by a
description. There can be multiple subject lines. The file may look
something like this:

   Subject: res_pjsip
   Subject: Core

   A description that explains the changes made and why. The release
   script will handle the bulleting and section separators!

   You can still separate with new lines within your
   description.

The headers ("Subject" and "Master-Only") are case sensative, but the
value for "Master-Only" ("true" or "True") is not.

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

ASTERISK-28111 #close

Change-Id: I19cf4b569321c88155a65e9b0b80f6d58075dd47

doc/CHANGES-staging/README.md

@@ -5,24 +5,28 @@ 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:
+it probably should. If there are multiple items that need documenting, you can
+add multiple files, each with their own description. If the message is going to
+be the same for each subject, then you can add multiple subject headers to one
+file. The "Subject: xxx" line 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
+> Subject: Core
 >
 > Here's a pretty good description of my new feature that explains exactly what
 > it does and how to use it.
+
+Here's a master-only example:
+
+> Subject: res_ari
+> Master-Only: True
 >
-> 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.
+> This change will only go into the master branch. The "Master-Only" header
+> will never be in a change not in master.
 
 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

doc/CHANGES-staging/bridging_stasis_cache.txt

@@ -0,0 +1,36 @@
+Subject: Bridging
+Master-Only: true
+
+The bridging core no longer uses the stasis cache for bridge
+snapshots.  The latest bridge snapshot is now stored on the
+ast_bridge structure itself.
+
+The following APIs are no longer available since the stasis cache
+is no longer used:
+  ast_bridge_topic_cached()
+  ast_bridge_topic_all_cached()
+
+A topic pool is now used for individual bridge topics.
+
+The ast_bridge_cache() function was removed since there's no
+longer a separate container of snapshots.
+
+A new function "ast_bridges()" was created to retrieve the
+container of all bridges.  Users formerly calling
+ast_bridge_cache() can use the new function to iterate over
+bridges and retrieve the latest snapshot directly from the
+bridge.
+
+The ast_bridge_snapshot_get_latest() function was renamed to
+ast_bridge_get_snapshot_by_uniqueid().
+
+A new function "ast_bridge_get_snapshot()" was created to retrieve
+the bridge snapshot directly from the bridge structure.
+
+The ast_bridge_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_bridge_snapshot_type() stasis message now has the
+ast_bridge_snapshot_update structure as it's data.  It contains
+the last snapshot and the new one.

doc/CHANGES-staging/chan_sip_deprecated.txt

@@ -0,0 +1,7 @@
+Subject: chan_sip
+Master-Only: true
+
+The chan_sip module is now deprecated, users should migrate to the
+replacement module chan_pjsip.  See guides at the Asterisk Wiki:
+  https://wiki.asterisk.org/wiki/x/tAHOAQ
+  https://wiki.asterisk.org/wiki/x/hYCLAQ

doc/CHANGES-staging/channels_stasis_cache.txt

@@ -0,0 +1,16 @@
+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.

doc/UPGRADE-staging/README.md

@@ -5,23 +5,27 @@ 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:
+are multiple items that need documenting, you can add multiple files, each with
+their own description. If the message is going to be the same for each subject,
+then you can add multiple subject headers to one file. The "Subject: xxx" line
+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
+> Subject: Core
 >
-> 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).
+> Here's a pretty good description of my new feature that explains exactly what
+> it does and how to use it.
+
+Here's a master-only example:
+
+> Subject: res_ari
+> Master-Only: True
 >
-> 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.
+> This change will only go into the master branch. The "Master-Only" header
+> will never be in a change not in master.
 
 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

doc/UPGRADE-staging/applications_jabberstatus.txt

@@ -0,0 +1,4 @@
+Subject: Applications
+Master-Only: true
+
+The JabberStatus application, deprecated in Asterisk 12, has been removed.

doc/UPGRADE-staging/bridging_stasis_cache.txt

@@ -0,0 +1,36 @@
+Subject: Bridging
+Master-Only: true
+
+The bridging core no longer uses the stasis cache for bridge
+snapshots.  The latest bridge snapshot is now stored on the
+ast_bridge structure itself.
+
+The following APIs are no longer available since the stasis cache
+is no longer used:
+  ast_bridge_topic_cached()
+  ast_bridge_topic_all_cached()
+
+A topic pool is now used for individual bridge topics.
+
+The ast_bridge_cache() function was removed since there's no
+longer a separate container of snapshots.
+
+A new function "ast_bridges()" was created to retrieve the
+container of all bridges.  Users formerly calling
+ast_bridge_cache() can use the new function to iterate over
+bridges and retrieve the latest snapshot directly from the
+bridge.
+
+The ast_bridge_snapshot_get_latest() function was renamed to
+ast_bridge_get_snapshot_by_uniqueid().
+
+A new function "ast_bridge_get_snapshot()" was created to retrieve
+the bridge snapshot directly from the bridge structure.
+
+The ast_bridge_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_bridge_snapshot_type() stasis message now has the
+ast_bridge_snapshot_update structure as it's data.  It contains
+the last snapshot and the new one.

doc/UPGRADE-staging/chan_sip_deprecated.txt

@@ -0,0 +1,7 @@
+Subject: chan_sip
+Master-Only: true
+
+The chan_sip module is now deprecated, users should migrate to the
+replacement module chan_pjsip.  See guides at the Asterisk Wiki:
+  https://wiki.asterisk.org/wiki/x/tAHOAQ
+  https://wiki.asterisk.org/wiki/x/hYCLAQ

doc/UPGRADE-staging/channels_stasis_cache.txt

@@ -0,0 +1,16 @@
+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.

doc/UPGRADE-staging/func_callerid_callerpres.txt

@@ -0,0 +1,5 @@
+Subject: func_callerid
+Master-Only: true
+
+The CALLERPRES() dialplan function, deprecated in Asterisk 1.8, has been
+removed.

doc/UPGRADE-staging/res_parking_parkingslot.txt

@@ -0,0 +1,5 @@
+Subject: res_parking
+Master-Only: true
+
+The PARKINGSLOT channel variable, deprecated in Asterisk 12 in favor of the
+PARKING_SPACE channel variable, will no longer be set.

doc/UPGRADE-staging/res_xmpp_jabberstatus.txt

@@ -0,0 +1,4 @@
+Subject: res_xmpp
+Master-Only: true
+
+The JabberStatus application, deprecated in Asterisk 12, has been removed.