[Bash-completion-devel] Policy for CHANGES

[Ville Skyttä]

On 04/27/2011 09:56 PM, David Paleino wrote:

> [ Upstream Name Surname ]
> * Fix blbla, patch by ThirdParty Contributor (Alioth: #...)
> 
> instead of making sections for each contributor (s/patch by/thanks to/ if you
> prefer)
> 
> Opinions?

No strong opinions, but if this is the direction we want to go, I'd prefer

[ Upstream Name Surname ]
* Fix blabla (ThirdParty Contributor; Alioth: #...)

But then again I'd like to see some more drastic changes to what gets
written in CHANGES and what not.  First, who are its target audience?
If it's end users, I think it currently contains entries that make no
sense to them or requires intimate knowledge, for example some picks
from the 2.x section:

* Add $_backup_glob for matching various backup files.
* If _filedir 'ext' returns nothing, just fallback to generic
  file completion. Patch by Clint Byrum (Debian: #619014, LP: #533985)
* Fix broken _allowed_groups usage (shadow and coreutils)
* Fix __get_cword_at_cursor_by_ref: check for $index when completing
  with a cword+1 argument already present (Debian: #622383)
* Improve __reassemble_comp_words_by_ref() to not create words of
  characters-to-exclude (Alioth: #313057)

If we want that level of detail, it could be generated from git logs and
we could ditch CHANGES altogether.

Also, if it's for end users, why would they care in the first place who
actually implemented/fixed what?

Personally I'd prefer that we write great git commit messages with
proper authorship info (possibly git commit --author depending on case)
and do not touch CHANGES at all during regular development.  The release
manager could maintain the CHANGES file or release notes somewhere else,
writing them in language that makes sense for end users, and picking
only high level entries that end users are generally interested in (e.g.
what completions were added/removed, what was improved, general
significant behavior/requirement changes, and possibly most prominent
bug fixes).  This could be done as part of release preparations.  Or if
there's nobody to write/maintain that info, we'd just generate CHANGES
from git logs.