build: Add staging directories for future changes.
[asterisk/asterisk.git] / doc / UPGRADE-staging / README.md
1 ## **DO NOT REMOVE THIS FILE!**
2
3 The only files that should be added to this directory are ones that will be
4 used by the release script to update the UPGRADE.txt file automatically. The
5 only time that it is necessary to add something to the UPGRADE-staging directory
6 is if you are making a breaking change to an existing feature in Asterisk. The
7 file does not need to have a meaningful name, but it probably should. If there
8 are multiple items that need documenting, each can be separated with a subject
9 line, which should always start with "Subject:", followed by the subject of the
10 change. This is case sensitive! For example, if you are making a change to PJSIP,
11 then you might add the file "res_pjsip_breaking_change" to this directory, with
12 a short description of what it does. If you are adding multiple entries, they
13 should be done in the same commit to avoid merge conflicts. Here's an example:
14
15 > Subject: res_pjsip
16 >
17 > Here's a pretty good description of what I changed that explains exactly what
18 > it does and why it breaks things (and why they needed to be broken).
19 >
20 > Subject: core
21 > Master-Only: true
22 >
23 > Here's another description of something else I added that is a big enough
24 > change to warrant another entry in the UPDATE.txt file.
25
26 Note that the second subject has another header: "Master-Only". Changes that go
27 into the master branch and ONLY the master branch are the only ones that should
28 have this header. Also, the value can only be "true" or "True". The
29 "Master-Only" part of the header IS case-sensitive, however!
30
31 For more information, check out the wiki page:
32 https://wiki.asterisk.org/wiki/display/AST/CHANGES+and+UPGRADE.txt