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

From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2019-11-05 22:43:21

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

Okey. It older entries can be ported gradually, I think.

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

FYI, w.r.t. release notes, regardless how file is named (CHANGELOG.md, NEWS.md,
CHANGES.md, RELEASES.md, etc.), I always assume `git log` is just used to query
raw data. Then, the data need to be manually edited into information.

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

I'm not suggesting it is or we do.

I just agree with that opinion that release notes and change log
are nowadays synonyms. Using Git we maintain commit history,
as it is named in Git docs and Git book,
not change log like we used to in CSV days :-)

> 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" :-)

OK :)

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