Release Bot

This is a bot to automate the release process for Market Dojo.

The eventual plan is for this to be run when a merge to Master is made. It should be part of a pipeline which generates the release notes from the bugtracker and PRs, cuts a release, triggers and babysits the deploy to live, and notifies anyone who cares about a given issue that it has been dealt with.

Features (i.e. things this does at this time):

• Cover marketdojo/auction. Infrastructure changes in auction-build are not reported, because that repository publishes no releases to derive a range from. A pull request's closing reference into a repository this tool does not cover is dropped with a warning before lookup. The pull request itself still appears in Other Changes
• Derive a head revision for each named release from the repository's own GitHub Releases. The head is the release's own tag, or its release-candidate branch when it has no tag yet. The tag is v<milestone> and the branch is rc-<milestone>. The head is resolved to its commit once, so a release-candidate branch that advances mid-run cannot select the base against one commit and the range against another
• Derive a base revision by ancestry, not by publication date. The base is the release tag nearest the head among the tags that are an ancestor of it. A hotfix tagged behind the release line is not the predecessor of a release ahead of it. The tool searches a bounded window of releases in its history for that ancestor
• Resolve that range into the pull requests between base and head. A pull request is in the release when its merge commit is an ancestor of the head revision. That merge commit must also not be an ancestor of the base revision. The run fails when:
  • a named release has neither a tag nor a release-candidate branch
  • a named release has a tag but no published GitHub Release, and no release searched is an ancestor of that tag
  • a named release has no ancestor tag among the releases searched, naming how many were searched
  • the base is not an ancestor of the head
  • no repository has a pull request in the range
  • a closing reference resolves to no issue
• --milestone is repeatable. Naming several releases unions their ranges. Each pull request appears once. A named release whose own range holds no pull requests is reported with a warning, so the union does not conceal it
• Fetch the pull requests found by the resolved range. The range selects pull requests in the report
• Fetch the closed issues those pull requests declare as closing references. An open issue is not reported, even if a pull request in the range closes it
• Report to the log, and to no file, how each named milestone diverges from that release's own range, before the union merges the releases together. The milestone selects nothing: it names the release, titles the report, and is a hygiene signal. A pull request in the range carrying a different milestone is not reported, because a pull request in the range is in the release whatever it carries. Reported are:
  • every merged pull request carrying the milestone that the range does not hold. Each one merged after the release was cut, or carries a milestone that needs moving
  • every open pull request carrying the milestone, reported apart from the merged ones. It was tagged for the release and never made it
  • every commit in the range with no associated merged pull request
  • a named release with no milestone at all, so nothing to compare against cannot read as a clean comparison
  • a comparison that could not be made at all, for the same reason. Divergence is advisory: a failure to report it is logged and the release notes are still written
• Generate categorised notes for the closing issues. Generate statistics for the range's pull requests
• Build a Markdown file with the release notes
• Typeset a PDF of the release notes, with no external tooling required

Plan (i.e. things this does not do at this time). Some of these may be done by GHA instead:

• Create Release in GitHub with the name of the current Milestone
• Trigger deploy process
• Email Admins to request smoke test on success, or to complain on failure
• Email support & clients to update on status of requested features/enhancements and bugfixes

Setup:

• Fetch the latest build from the Releases section of this repository on GitHub
• Create a GitHub token with the repo scope and set it as an environment variable GITHUB_TOKEN
• Ensure you know the milestone's name. It is the release version, for example 16.0.5
• Run with release_bot --milestone <version>. The tool derives the base and head revisions itself
• The release notes will be generated in the releases directory