Re: [RFC] CHANGELOG.md based on keepachangelog.com

From: stefan (stefan_at_[hidden])
Date: 2019-11-05 16:39:14

Hi Mateusz,

thanks for your initiative !

On 2019-11-05 11:23 a.m., Mateusz Loskot wrote:
> First, we need content for the file, so I'd like to retrospectively collect
> our release notes from boost.org website.

I agree (but only for a few releases, to give ourselves an upper bound).

> My question is, what format/convention shall we use?
>
> Assuming (correctly?) our requirements are:
>
> 1. Single file
> 2. Markdown format
> 3. File at the top-level of the repository
> 4. No automation or scripting for gathering, compiling or formatting.
>
> I'd like to propose CHANGELOG.md file based on this convention:
> https://keepachangelog.com
>
> Pros:
> - simple, no-brainer
> - well-known, well-established convention
> - produces clear, user-oriented notes
> - covers all types of entries,
> - no dependencies, no scripting
> - needs no custom documentation for GIL release manager
> - future-proof, not prone to bus factor
>
> Cons are unknown.
>
> Please, discuss.

I think this is a good idea, and I like the format, with one caveat: I'd 
really prefer to call it "release notes" rather than a "change log". I'm 
old enough to remember CVS and the GNU style of changelogs that we 
(manually) generated at that time. This approach was obsoleted by the 
gradual migration to more modern versioning control tools that supported 
"commit messages", so a change-log file could be auto-generated from those.

My objection is that change logs really have a different purpose than 
release notes. The former are targeted at developers ("You can think of 
the change log as a conceptual “undo list”": 
https://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html#Change-Log-Concepts), 
and for that I really don't see any need with powerful tools such as git.

Release notes, however, provide a higher-level overview of changes 
affecting users, such as API changes, new features, important bug fixes, 
etc.

In either case, I think the proposed format (as well as usage policy) 
works fine for both, so I'd be happy to adopt it. I'd simply name the 
file `release_notes.md` rather than `changelog.md` to better represent 
the purpose.

Thanks,

Stefan

--
       ...ich hab' noch einen Koffer in Berlin...