Modify the release process so that a release candidate is visible in a PR?

[danielfromearth]

@jhkennedy, as we mentioned during the Hackday today, shouldthe release process be modified so that release candidates are visible in a PR, say e.g., using a different branch like release/10.0.0?

I think this has been brought up in various other hackday discussions, and was mentioned in #833.

[jhkennedy]

Motivations

In general, my motivation for this is:

1. I want to be able to open a draft release PR from main and see the current state of main compared to the last release
   (implied is that I'd prefer this to be updated automatically anytime something is merged to main)
2. I want releases to be reviewed and the review to be an async process
3. I want it to be as automated as possible so we can release faster, with fewer errors, and minimize manual work
4. I want to make the processes easier on potential contributors

I'm interested to hear if there are other motivations or disagreements/etc. with these motivations?

Challenges

There are a couple of challenges/issues with automating releases:

1. Releases will generally require at least a little manual work in a release feature branch because we need to run bump-my-version to pick a new version number and:

   • in the changelog, change

     ## [Unreleased]
     

     to

     ## [Unreleased]
     
     ## [NEW_VERSION] - YYYY-MM-DD
     

   • at the bottom of the changelog, change

     [Unreleased]: https://github.com/nsidc/earthaccess/compare/OLD_VERSION...HEAD`
     

     to

     [Unreleased]: https://github.com/nsidc/earthaccess/compare/NEW_VERSION...HEAD`
     [NEW_VERSION]: https://github.com/nsidc/earthaccess/releases/tag/vNEW_VERSION
     

2. There's a race condition possible where a PR is merged into main between the time a release is reviewed/approved and the merge is reflected in main.

3. Releasing a subset of the change in main if not all merged features are release-ready or allowing hot fixes to previous releases may require a special process.

4. [The big one] We currently want the release notes to be manually curated according to our release docs (see step 4 here)

   We hand-curate our release notes to be valuable to humans. Please auto-generate release notes, but replace the "What's changed" section with the Markdown from the new CHANGELOG section for this release. Retain the "New contributors" and "Full changelog" text generated by GitHub.

Proposed implementations

1. single-truck (main) with release feature branches which get squashed to main

Since earthaccess developers typically prefer a single-truck branch (main) and squash commits, I think the easiest way to automate releases would be to:

1. create a release branch and bump the version number with bump-my-version via either:

   1. doing it manually, which would be something like:

      git switch main
      git pull --ff-only upstream/main
      bump-my-version bump [LEVEL]
      export NEW_VERSION=$(bump-my-version show current_version)
      git switch -c "release/v${NEW_VERSION}"
      git commit -am "Bump version to ${NEW_VERSION}"
      git push -u origin "release/v${NEW_VERSION}"

      and then opening a PR to main

   2. a new "make-new-release" workflow you can trigger with a workflow dispatch that takes a bump part (major/minor/patch) as input and does (i) for you

2. PRs from a release/v* to main trigger:

   • Changelog check to ensure there's a matching changelog entry for the new version number
   • a release label is attached
   • all the test runs (this should already happen with our current CI/CD)

3. Merges from a release/v* branch to main trigger:

   • a new tag is created matching the version number

4. New tag pushes trigger:

   • a GitHub Release is published with the corresponding changelog entry as the body

5. New releases trigger:

   • Our publish.yml workflow to publish on PyPI

This will generally work fine for most workflows, and as for the challenges:

• ✔️ bump-my-version handle challenge (1)
• 🆗 Appropriate branch protection rules can handle challenge (2), but syncing will likely have to be manually done ☹️
• ⚠️ there's no clear way to handle challenge (3), so that will always be ad-hoc (if we release often, this should be uncommon). Additionally, using tools like hatch-vcs requires all tags to be in the branch history, so we'd have to remember to merge those tags back into main with a merge commit ☹️
• ❓ For challenge (4), now that we've fully adopted Common Changelog, I don't think we need to hand-curate our workflows anymore -- we'd have to either generate the "new contributors" and "Full changelog" automatically or drop them, but since they are already generated by GitHub automatically for us, figuring out how to automate it shouldn't be a problem.

2. A long-lived release branch we merge from main into

An alternative would be to create a long-lived release branch (e.g., release) that we merge into to create new releases. That would look like:

1. A PR is opened from main to release which triggers:

   • a check to ensure there's a major, minor, or patch label applied (if we automate the next step)
   • Changelog check to ensure there's a matching changelog entry for the new version number (based on the predicted version from using the label)
   • a release label is attached
   • all the test runs (this should already happen with our current CI/CD)

2. Initially (1) will fail until a PR into main has bumped the version number with bump-my-version, which could be automated/triggered from the previous step, but risks the release date not matching the date the tag was created if the review takes more than a day (we could write a check for this or include it in the changelog check).

3. Merges from main to release trigger](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#running-your-pull_request_target-workflow-when-a-pull-request-merges):

   • a new tag is created matching the new version number

4. New tag pushes trigger:

   • a GitHub Release is published with the corresponding changelog entry as the body
   • the release branch is fast-forward merged back into main to keep the linear history (if this fails, a PR is opened instead)

5. New releases trigger:

• Our publish.yml workflow to publish on PyPI

With this workflow, our git history would largely look the same, except merge commits would demarcate releases, and tags would be attached to those merge commits. We'd want branch protection rules to ensure merges to main (and not from release) are squashed, but merges to release are merge commits. As for the challenges:

• 🆗 bump-my-version handles challenge (1), especially if automated, but the changelog release date could get out of sync from when the tag is created if not checked (either by the reviewer/merger or automatically) ☹️
• ✔️ the PR will always be in sync with main, and the fallback PR solves the issue where something comes into main before the release branch is fast-forward merged to main.
• ✔️ this workflow can easily support hotfixes and subsets by opening a PR to release from not-main, which will be reflected in main via the fallback merge PR. Additionally, using tools like hatch-vcs is just fine as all tags will be in the branch history
• ❓ For challenge (4), now that we've fully adopted Common Changelog, I don't think we need to hand-curate our workflows anymore -- we'd have to either generate the "new contributors" and "Full changelog" automatically or drop them, but since they are already generated by GitHub automatically for us, figuring out how to automate it shouldn't be a problem.

---

Overall, either would be fine -- I generally prefer solution (2) as I think it's easier and more flexible. I've already developed almost all of the CI/CD for it as we use merge-commits and a main/release setup for HyP3 (though the branches are named develop/main there), so it'd be easy to implement. That said, (1) is also straightforward to implement and closely matches our preferred development workflow but doesn't really support hotfixes and subset releases, which are infrequent (though occasionally needed).

[mfisher87]

For challenge (4), now that we've fully adopted Common Changelog, I don't think we need to hand-curate our workflows anymore

💯

I think I also prefer (2)!