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

From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2019-11-05 17:38:47

On Tue, 5 Nov 2019 at 17:39, stefan <stefan_at_[hidden]> wrote:
> 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).

Anything wrong if I manage to get in all notes or notes from GIL
review for Boost?
I'll see how things roll.

> > 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.

I remember those times, but that notion of change log is not obsolete really.

> My objection is that change logs really have a different purpose than
> release notes. The former are targeted at developers
> (...)
> Release notes, however, provide a higher-level overview of changes
> affecting users, such as API changes, new features, important bug fixes,
> etc.

That is exactly what https://keepachangelog.com promises:
it is a file with curated notes dedicated to end users.
And...

> I'd simply name the file `release_notes.md` rather than
> `changelog.md` to better represent the purpose.

I buy the rationale explained on keepachangelog.com

"""
What should the changelog file be named?
Call it CHANGELOG.md. Some projects use HISTORY, NEWS or RELEASES.
While it's easy to think that the name of your changelog file doesn't
matter that
much, why make it harder for your end users to consistently find
notable changes?
"""

In top-level, we have end-user's README.md, developer's CONTRIBUTING.md,
and everyone's CHANGELOG.md name fits there very well,
and to GitHub convention too.
Single word upper-case name makes it clear what files fall into the bag
of the few essential files that are essential to read.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net