[RFC] CHANGELOG.md based on keepachangelog.com

From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2019-11-05 16:23:53

Hi,

Recently, Stefan and I, we had a chat about maintaining release notes
in a single Markdown file inside GIL repository and
displaying it as part of GIL documentation.

I have been researching technical aspect of integrating such file
into Sphinx documentation, it's feasible. There are 2 or 3 ways
at least to implement it, so we will be able to choose one we prefer.

First, we need content for the file, so I'd like to retrospectively collect
our release notes from boost.org website.
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.

(Note, I'm not proposing to follow semantic versioning - if anyone
likes to see GIL internally use it, please make a separate proposal.)

Once we have decided how to write the CHANGELOG.md,
I will port the old release notes  and implement integration
into the documentation.

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