From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2019-11-05 16:23:53
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:
- 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.
(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.
-- Mateusz Loskot, http://mateusz.loskot.net
Boost list run by Boost-Gil-Owners