Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[release automation] Changelog fragments management #454

Open
webknjaz opened this issue Dec 5, 2021 · 3 comments · May be fixed by #469
Open

[release automation] Changelog fragments management #454

webknjaz opened this issue Dec 5, 2021 · 3 comments · May be fixed by #469
Labels
documentation Improvements or additions to documentation enhancement New feature or request

Comments

@webknjaz
Copy link
Contributor

webknjaz commented Dec 5, 2021

Description / Summary

I noticed that currently CHANGELOG.md is being managed manually. I have recently figured out how to configure Towncrier to work with Markdown so I wanted to ask if you want a PR integrating that. I also have a few companion integration — a GitHub App for a check on PRs and a Sphinx extension for rendering the upcoming changes.

Value / benefit

This would reduce some of the maintenance burden connected to the release preparation. I could also improve some of the surrounding automation to reduce human error (the extended series contributions would take a bit more time, though).

Implementation details

No response

Tasks to complete

No response

@webknjaz webknjaz added the enhancement New feature or request label Dec 5, 2021
@chrisjsewell chrisjsewell added the documentation Improvements or additions to documentation label Dec 6, 2021
@chrisjsewell
Copy link
Member

Thanks for the offer @webknjaz!
I would certainly be interested to see how it works.

I would note though, my opinion on the changelog is that, at least the initial section, should be easily digestible by "non-technical" users, i.e. more of an explanation of the changes rather than just a list of commits (which you can just go to GitHub to see).
An exemplar of this IMO is https://code.visualstudio.com/updates/v1_62, where you have descriptive documentation at the start, then the PR list at the bottom.
If Towncrier could allow for this kind of workflow (part manual, part auto-generated) that would be great

(Also FYI, within EBP repos I was initially just using https://github.com/executablebooks/github-activity, but moved away from this.)

@webknjaz
Copy link
Contributor Author

I agree with that opinion and that is exactly why Towncrier and similar workflows are valuable. Each PR must include a changelog fragment file, these files are accumulated in a folder but when the release is needed, you'd run towncrier and they'd be removed and rendered into the normal changelog file. There are markers in such a changelog file and towncrier adds new release section below such a marker allowing you to have arbitrary text above it. You can include that changelog file in Sphinx as needed too.

I usually include a section with an explanation for the contributors on how it works. Here's what I added in setuptools, for example, https://setuptools.pypa.io/en/latest/development/developer-guide.html#making-a-pull-request.
I also like to emphasize that the writing style for the changelog entries must be quite different from what one would expect from commit messages. Traditionally, commits should use the imperative mood while changelogs describe what's happened already since the last release, hence they need to be in the past tense most of the time (or using another way to convey the changed state). And the audiences for these types of content are different, commits are for developers/contributors, they may go into technical detail and motivation; changelogs are for the end-users, they need to describe the high-level impact of the user-facing changes, the UX side of the story.

Here's one of the projects where it's implemented: https://ansible-pylibssh.readthedocs.io/en/latest/changelog/.

By the way, here's a public resource that documents why dumping git log is bad: https://keepachangelog.com/en/1.1.0/#bad-practices.

P.S. Towncrier generates the changelog content based on a Jinja2 template which makes it very flexible and you can improve it anytime. Plus, once you generate changelog, you can edit the changelog file as you wish too.

webknjaz added a commit to webknjaz/MyST-Parser that referenced this issue Dec 20, 2021
@webknjaz webknjaz linked a pull request Dec 20, 2021 that will close this issue
webknjaz added a commit to webknjaz/MyST-Parser that referenced this issue Dec 20, 2021
webknjaz added a commit to webknjaz/MyST-Parser that referenced this issue Dec 21, 2021
webknjaz added a commit to webknjaz/MyST-Parser that referenced this issue Dec 21, 2021
@webknjaz
Copy link
Contributor Author

@chrisjsewell I think this #469 should demonstrate how this works + show what parts are adjustable.

webknjaz added a commit to webknjaz/MyST-Parser that referenced this issue Oct 19, 2022
webknjaz added a commit to webknjaz/MyST-Parser that referenced this issue Oct 19, 2022
webknjaz added a commit to webknjaz/MyST-Parser that referenced this issue Oct 19, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants