Start tracking a changelog

[aphelionz]

Can be in any format as long as it serves the purpose.

Inspiration

• https://github.com/conventional-changelog/standard-version
• https://keepachangelog.com/en/1.0.0/
• https://www.gnu.org/prep/standards/html_node/Change-Logs.html

Issue can be closed when:

• Changelog format is chosen
• Changelog is created and / or stubbed out
• Changelog protocol is written in CONTRIBUTING.md

[koivunej]

TIL there are specs for changelogs.

standard-version seems all encompassing tooling, which would require conventional commits and so on. GNU examples include stuff like * sort.el (sort-subr): Return nil. as a positive example which makes me think they were programmatically produced like the standard-version.

The second links acknowledges the unparseability but splits to added/changed/deprecated/removed/fixed/security.

A more straightforward alternative used in rust-libp2p would be: each PR should include a new line to CHANGELOG.md, which is like $submodule: header [PR NNNN](https://github.com/libp2p/rust-libp2p/pull/NNNN). I think this is the only one related to github PR workflow as it assumes there is useful discussion in the pull requests themselves and would thus work instead of adding an additional editorialization phase, like rust does. "editorialization phase" as in during releasing people the people working on the release go throught the changes and write the release notes. Note the similar structure though, unordered list items linking the PR.

Of the above I'd lean towards the style used by rust-libp2p.

[vmx]

The advantage of conventional commits is, that you normally also end up with a nice/clean history on Git. You could e.g. easily see breaking changes in the history and look at the diff what they are about without getting back and forth in the changelog.

Though a down-side is that it puts extra work to the people that merge code as contributions from external contributors might need to change the commit message before merging (though this can be done through the GitHub UI when mergeing).

[aphelionz]

Thanks @vmx. We'll consider that. I agree and my issue with conventional commits is enforcement. If we can get a git hook in place to slap people's wrists so I don't have to that would be fine, but I have to admit I'm not able (and perhaps not willing) to be a watchdog in that regard. 🤔

[aphelionz]

Another question, would it make sense to write a changelog entry number 0 that details what we have so far? Perhaps call it reloease 0.1.1 or something?

[vmx]

but I have to admit I'm not able (and perhaps not willing) to be a watchdog in that regard.

If manual changelog entries are needed, someone would need to watchdog those too.

[aphelionz]

I can automate that with GitHub Pull requests templates that include a checkbox i.e.

• verify that all checks pass
• get approval from contributor
• squash commits
• Edit changelog.md

[vmx]

Checking the conventional commit message could also be a checkbox :) It could even be checked by CI if it has the correct syntax, the semantics of course would still need to be checked by a human.

[aphelionz]

Ok, copy that. I'll take a first crack at all this and report back!

[koivunej]

The #400 has my proposal for this, which is essentially the simplest form I've been keeping in unixfs/CHANGELOG.md.