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

From: stefan (stefan_at_[hidden])
Date: 2019-11-05 20:33:02

On 2019-11-05 12:38 p.m., Mateusz Loskot wrote:
> 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?

Not at all. Just trying to limit the amount of work. :-)

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

No, but it can be extracted from commit messages, i.e. `git log` plus 
some filtering.

>> 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?
> """

Sorry, I don't understand the argument. It's not as if the whole world 
is using "CHANGELOG.md", with only us trying to deviate.

In fact, I know more projects using the term "news" or "release notes" 
than "change log", so if anything, the argument goes exactly the other 
way. :-)

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

No problem with that. Let's call it  "RELEASE.md" :-)

Stefan

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