Document release process using rever

[jezdez]

What is the idea?

We recently migrated the changelog/release notes to Markdown to improve the relase process (using rever) and it turns out that the changelog functonality of rever doesn't quite work with our rever setup because it doesn't pick up the custom regex pattern for the Markdown header to automatically update the file. Instead it just deletes the news file it's supposed to add and doesn't update the changelog.

Why is this needed

It seems as if rever is mostly targeted at restructured text, I think we should revert back to that format. Or stop using rever all together. I'm not sure if the tool provides much value on top of other tooling for autmatically updating the changelog versus simply updating it manually.

What should happen?

We should have a release process that is at least semi-automatic in updating the changelog based on the commits that happned since the release and reduce the moving pieces that could prevent the release from being simple.

Additional Context

I've used a similar tool before that may be better suited for the task: https://github.com/twisted/towncrier

[kenodegard]

Current workflow

1. Install rever:

   $ conda create -n rever conda-forge::rever

2. Run rever --activities authors, include --force if you have previously run this activity for the given <VERSION>:

   $ conda run -n rever rever --activities authors <VERSION> [--force]

3. Review commit containing updates to author files (.authors.yml, .mailmap, and AUTHORS.md).
   • Only make changes to .authors.yml and only make changes to the name/email, github, or aliases/alternative_emails keys. Other keys (e.g. num_commits or first_commit) is repopulated every time you run rever. Commit these manual modifications separately from the rever commit.
   • Manual changes to .mailmap or AUTHORS.md are ignored and overwritten when rever is rerun.
   • Beware of changes that result in modifications to .mailmap, if .mailmap is modified during the rever run you will need to extract that modification and commit it separately and then rerun rever --activities authors.
   • E.g.:

     $ conda run -n rever rever --activities authors 4.13.0 --force
     # if it produces a git commit that modifies .mailmap continue with the following
     $ git reset HEAD~1 --soft  # undo commit
     $ git checkout HEAD~1 -- .authors.yml AUTHORS.md  # undo changes
     $ git add .
     $ git commit -m "Updated .mailmap for 4.13.0"

   • Check that your .mailmap is correct by running git shortlog -se and comparing it to AUTHORS.md, if they have any discrepancies additional modifications to .authors.yml is needed.
4. Review news snippets and add additional snippets for undocumented PRs/changes as necessary.
5. Run rever --activities changelog, include --force if you have previously run this activity for the given <VERSION>:

   $ conda run -n rever rever --activities changelog <VERSION> [--force]

   • This is a notoriously fickle step where rever may simply fail to generate the changelog blurb. If it fails to modify CHANGELOG.md you'll find the blurb in rever's working directory and you can manually format and commit the blurb.
6. After successfully running the actions separately it's ideal to undo those commits and to run both actions simultaneously (the changelog will only include the contributors if the authors action is run concurrently with the changelog action).
7. Rever does not include stats on first-time contributors so if we want to include this info use the auto-generated release notes from GitHub releases and manually aggregate that info into rever's changelog commit.

Comments

To make a clean release the release manager will need to be very comfortable with git rebase, git squash, and git commit --amend.

Discussion

This process is pretty heavy-handed especially if any modifications are needed to the author mapping and doesn't even produce the correct commit count (compare num_commits in .authors.yml to the counts in git shortlog -sne). But if there are other tools out there that do a better job with the news snippets/changelog process there's likely low value in keeping rever since generating a valid .mailmap isn't all that hard to do manually (even using a super simple bash+git script wouldn't be very complicated).

[kenodegard]

With the conda-build 3.21.9 release (conda/conda-build#4483) I took the opportunity to rework the rever setup from RST to MD. Overall I feel that there isn't anything wrong with how we are using rever but as the above process indicates it's perhaps a little too heavy-handed to get right.

Researching alternatives in #556