[asterisk-dev] Policy regarding CHANGES and UPGRADE files in Asterisk branches

[John Todd]

On Nov 19, 2008, at 5:11 AM, Kevin P. Fleming wrote:

> While merging the agi_multiple-api-fix branch into trunk, 1.6.1 and
> 1.6.0, I've found that apparently the contents of these text documents
> are not well understood, and that developers are putting entries into
> the wrong files. I'll reiterate the policies for what these files  
> should
> contain:
>
> UPGRADE.txt (and any files it refers to) must contain entries for  
> every
> change that an upgrader *must be made aware of*. This is generally due
> to the change forcing configuration changes, providing
> non-backwards-compatible behavior, or something similar. In other  
> words,
> it's the 'if you are not going to read any other documentation while
> upgrading, at least read this one' file.
>
> CHANGES must contain entries for all user-visible functionality  
> changes
> not already listed in UPGRADE.txt.
>
> As to why one of them has a 'txt' extension in the file name and the
> other doesn't, the reason for that is probably lost in the mists of  
> time :-)

Perhaps it might be useful to put these descriptions that you provide  
below as the first block of text in each file might create a permanent  
reminder so that those modifying the files will be continually  
reminded of the purpose of each file.

JT

---
John Todd
jtodd at digium.com        +1-256-428-6083
Asterisk Open Source Community Director