Add release workflows

[kurtmckee]

Breaking changes

• tox: Add a timeout-minutes key for configuring job timeouts.

  Jobs now timeout after 15 minutes by default.

Added

• Introduce a create-pr workflow.

  This workflow runs a tox label, commits the changes, and opens a PR.

• Introduce a create-tag-and-release workflow.

  This workflow creates an annotated git tag and a GitHub release.

• Introduce a build-python-package workflow.

  This workflow builds a Python package and uploads an artifact.

Changed

• Lock almost all software dependencies.
• Update all software dependencies.

Documentation

• Add extensive documentation for almost all of the workflows.

Development

• Use templates to generate standalone reusable workflow files.

  Now, instead of disallowing edits to portions of the workflows,
  the underlying templates are fully editable.

• Use prek to update pre-commit hook versions.

• Wholesale copy all of the infrastructure from kurtmckee/github-workflows.

  This ensures that this repo can evolve independently as needed.

[derek-globus]

I'm not sure I see the light of shifting our releasing process to heavily automated github workflows. Maybe you and I could discuss more offline.

My biggest concerns are:

Complexity

The processes we perform today during a release are manually invoked on a local machine but (for the most part) use transparent tooling where the operator knows exactly what's happening when they click a button.

With these proposed workflows, in large part due to the frequent context switching between different languages and tools, I struggle to understand the hundreds of lines of code that are "creating a PR" or "creating a tag and release". If those were complex operations, I would be more amenable to encapsulating the complexity but (at least in name)they aren't. PRs, releasing, and tagging are all pretty commonplace operations we do.

Robot Content Moderation

This one may be my failing to understand the process but I'll explain the concern so we can talk about it.
As it stands today, we have 2 big touchpoints for content curation:

1. Scriv collection - a (potentially large) number of changelog fragments get aggregated together into a single human-targeted view.
2. Release writing - the recently-generated changelog gets turned into a human-readable piece of github content.

It looks like these processes are trying to automate away both of those points of contact and I don't think we should. Frequently changelog fragments don't fit well together. Imo they should always be manually curated; even if to have a human look and say "no that looks fine with scriv's normal collection".

[sirosen]

This PR has been in my backlog to review, but I don't know when I can devote my attention to it in full.

I support automating release processes but I think that should start from the point at which changes to the project (changelog, version number, etc) have been prepared and reviewed. Not necessarily merged though.

As an example of what I would like to see, we could have a workflow which starts from a prompt to release from PR #100, which

• checks out the PR
• validates that it changes the version number vs main
• builds artifacts for the current version
• runs tests on those artifacts
• publishes those artifacts to repositories (e.g., PyPI)
• creates any secondary bookkeeping artifacts (e.g., GitHub Releases, tags)
• merges

In particular, I agree with this one of Derek's notes:

Frequently changelog fragments don't fit well together. Imo they should always be manually curated; even if to have a human look and say "no that looks fine with scriv's normal collection".

With scriv, towncrier, and even an "unreleased" changelog section, you frequently need to make final edits. e.g., Catching inconsistent tense for "Fix bug 101" vs "Fixed bug 102".

That finalization of a release changelog and the review process at that stage are our final check and last chance for issues to be raised. e.g., "We added feature X, so this should be a feature release, not a patch."

[kurtmckee]

@derek-globus re: robot content moderation

The create-pr reusable workflow is intended to be used via a callable workflow in the repository that uses it. Here's a snippet from a repository's workflow that already relies on this reusable workflow:

on:
  workflow_dispatch:
    inputs:
      version:
        description: "The new version"
        type: "string"
        required: true

which gives this GitHub UI:

A human necessarily makes a decision what version number to use.

---

Second, the PR is opened in WIP mode. It's impossible to merge the PR until a human makes a decision. A human should review the CHANGELOG and edit the file, just as if they were doing so locally. However, they don't have to leave the GitHub interface to do so -- they can edit and commit the changes directly in the PR view. Here's what this looks like in this PR:

and this is what the commit interface looks like when clicking "Commit changes":

---

Third, regarding complexity, it is entirely possible to do all of this manually. We currently rely on "human scripting" to accomplish this -- documentation that must be rigorously followed in each repo, commands that must be correctly copied and pasted to our shells, and helper shell scripts that must be adapted to work on both Linux and macOS. In fact we even have to address repo cloning and forking differences between developers (the git remote origin vs upstream naming issue that has forced our release documentation to also include conditional text that must also be perfectly -- and manually -- executed).

These workflows migrate that complexity from the developer's choice of operating system, choice of git clone/fork, choice of shell, possible git aliases, and all other possible differences, to these reusable workflows. The human choosing to cut a release would therefore:

1. Use the "create a release PR" UI shown above
2. Edit the CHANGELOG, if needed
3. Click "merge" on the release PR.
4. see note, below

On the other side of that process, they can expect to see all git, GitHub, and PyPI artifacts and resources created.

NOTE: It may still be necessary to open a PR to merge the releases branch back to main. GitHub already supplies a two-click UI for doing this:

I haven't yet tested opening the merge-back PR automatically; I think a few changes might be needed, but these provide the infrastructure.

---

Finally -- let's discuss more offline.

[derek-globus]

Okay, that answers my robot moderation question which was the bigger hurdle in my head.
I'd like to make sure that the info you provided gets included in our orchestration steps but am satisfied for the sake of this PR that the process includes a human at that point.

---

Will reach out offline to discuss complexity.

[derek-globus]

Review 1: everything not in the directories:

• .github/
• src/
• test/

[derek-globus]

Review of the rest of the code.

The regular execution paths look good to my eyes; I don't think that any of the actual execution components seem problematic.