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

Enable towncrier for changelog aggregation #90

Merged
merged 4 commits into from
Oct 5, 2023
Merged

Conversation

diazona
Copy link
Owner

@diazona diazona commented Oct 5, 2023

This PR sets up the configuration and infrastructure for towncrier to maintain our changelog. Going forward, every pull request should contain a changelog fragment. We can add something to verify that, but I've decided to omit that from the scope of this PR because I don't want to stretch it out too long.

With this change, our procedure for releasing the package (previously outlined in #40) gains an extra step:

  1. After everything else needed for the release has been done, locally create a branch and run tox run -e towncrier -- version {version} (where {version} is a placeholder for the actual version number we want to release). That will generate the changelog entries. Commit the changes, push the branch, make a PR, and get it merged by the usual process.
  2. Then make a Github release (referring to the announcement page on Github that we make using this form), with a corresponding tag v{version}, in the Github web interface (or by using the Github API) - this is step 1 from the first list in the description of Rewrite the release workflow and refactor existing GHA workflows #40.
  3. Continue with the rest of the procedure as laid out in that list.

It's going to be a little tedious at first, but I think this is not too bad. In the future, we can definitely make this more automatic e.g. by adding a Github workflow to run through some of these steps, but it may be better to switch around some of the steps the release procedure, perhaps along the lines of one of the alternatives described in #40. I think we need some time (and maybe experience) to figure that out, so I've chosen to defer doing anything more complicated for a future PR. (Open to discussion, as always)

Closes #88 (and take note of the discussion happening there before deciding whether to merge this!)

This commit sets up the configuration for towncrier. We'll put changelog
fragments in the directory changelog.d, which is being created (or
technically a stub file to ensure it always exists), and they will be
accumulated into CHANGELOG.rst, which I think is a pretty common name
and is consistent with other changelog-related terminology. I've renamed
NEWS.rst to CHANGELOG.rst accordingly.
This hook just does some basic sanity checks on the changelog fragments.
I've chosen not to use the update hook because I'm not sure how it would
interact with setuptools-scm (which changes the version number on every
commit), and it might not even be a good fit for our workflow anyway.
I believe that jaraco.develop.finalize is not the right tool for us to
use when preparing for a release. For one thing, when I run it I get
errors about a missing dependency (tomlkit); probably more importantly,
it seems to do a few things that are incompatible with the way we have
this project set up, like creating an unused newsfragments directory and
adding some random files to Git. I haven't fully investigated this but I
think there is minimal benefit in using jaraco.develop.finalize compared
to just running towncrier directly.

So I've modified the tox environemnt to do just that. I changed it to
actually install the package to avoid and problems with missing
dependencies (although it's possible that wasn't the right way to fix it
but we can figure that out later) and I replaced the previous command
with a simple invocation of `towncrier build`. I also changed
the environment name to `towncrier` to reflect its new role.

Note that when preparing a release, we'll have to pass the --version
option to towncrier (or, to `tox run -e towncrier`) manually for now. I
hope that in the future we can automate that process.
This is supposed to be an example of how we should be handling changelog
fragments, but it also serves to document the change of enabling
towncrier. There should be one of these files in every pull request
going forward.
@diazona diazona added the documentation Improvements or additions to documentation label Oct 5, 2023
@diazona diazona added this to the Initial release milestone Oct 5, 2023
@diazona diazona requested a review from sjlongland October 5, 2023 07:00
@diazona diazona mentioned this pull request Oct 5, 2023
@diazona
Copy link
Owner Author

diazona commented Oct 5, 2023

P.S. I am very tired at the moment and could easily have made a few silly mistakes, so a nice careful review of this code would be especially appreciated 😄

@sjlongland sjlongland merged commit 435166f into main Oct 5, 2023
10 checks passed
@sjlongland sjlongland deleted the towncrier/1/dev branch October 5, 2023 07:44
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
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Enable towncrier
2 participants