Proposal for interim release process

[lance]

Interim Release Process Proposal

I've been thinking recently about the next release, and reviewing both the Knative release machinery, and the release-please module which we have been historically using via the release-please-action GitHub action in ci.yaml. The following is a strawman proposal for moving forward with an interim process that we can refine and improve over time. The goals with this initial proposal are to

1. begin adopting the Knative machinery
2. ensure that we can release v0.20.0 prior to the upcoming December holidays
3. continue to have (semi-)automated updates to CHANGELOG.md and version.txt
4. continue to have (semi-)automated releases at https://github.com/knative-sandbox/kn-plugin-func/releases
5. resolve the Knative org concerns about GH actions force pushing to protected branches

TL;DR

Use a combination of release-please and Knative tooling to get about 90% there.

Current Workflow

So that everyone is clear about what we are doing today, I have briefly outlined what happens in our CI as code lands on main. The GitHub workflow that we have been using does the following.

• Each time code lands on main, in ci.yaml, release-please-action runs.
• The release-please-action examines the commit message, and updates the CHANGELOG.md file based on the use of conventional commit messages.
• The release-please-action commits these updates to CHANGELOG.md in a release-vX.Y.Z branch, which mirrors main
• The release-please action looks for a PR from the release branch to main
  • if found, the body of the PR is updated to include the new changes
  • if not found, a PR is created - see, for example, chore: release 0.20.0 #667
• When the release PR itself lands on main, the release-please-action creates a draft release at https://github.com/knative-sandbox/kn-plugin-func/releases
• If a draft release was created we do the following
  • tag the commit with vX.Y.Z
  • gzip all binaries that were created with make cross-platform
  • upload the binaries to the draft release post

There are two specific and tangible problems with this. First, the Google CLA bot does not like commits from a GitHub action. Second, the Knative machinery protects release* branches from force pushes by actors such as a GitHub action. In order to effectively release func we must address both of these issues. And for overall Knative alignment, we need to begin adopting some of the current Knative release processes as defined in https://github.com/knative/hack/blob/main/release.sh.

Strawman Proposal

The ideas here are loosely formed and I welcome feedback.

Keeping CHANGELOG.md and version.txt up to date on a release branch

The release-please-action GitHub action is based on a Node.js CLI called release-please. This CLI can be used to manage the CHANGELOG.md and version.txt files on the release branch from a fork repository. Running the following CLI command in a local clone successfully creates/updates a release PR with appropriate changes to the CHANGELOG.md file. (This is how I created the 0.20.0 release PR #667)

release-please --repo-url https://github.com/knative-sandbox/kn-plugin-func --fork true --bump-minor-pre-major true --token $GITHUB_RELEASE_PLEASE_TOKEN --release-type simple release-pr

This satisfies 3) and 5) above - mostly. It would be better if we can work out a way to automate this - perhaps from a Boson mirror of the repository.

Creating a release

With some form of the above, we get the automated CHANGELOG and version.txt updates. But the actual release itself is not created. To do that we have a couple of options. If we want to stick with release-please it is possible to generate the release from the CLI as well with the following command. NOTE this command should be run after the release PR has landed on main.

release-please --repo-url https://github.com/knative-sandbox/kn-plugin-func --fork true --bump-minor-pre-major true --token $GITHUB_RELEASE_PLEASE_TOKEN --release-type simple --draft true github-release

This will create a draft release at https://github.com/knative-sandbox/kn-plugin-func including the all of the updates to the changelog. Here is the most recent release that was created as a draft by release-please. It would be nice if this could be automated. Doing this would take care of 2) and 4) above, but we've still left out 1). We're still not doing anything with the Knative release tooling.

The specific tooling I refer to is the hack/release.sh script here: https://github.com/knative/hack/blob/main/release.sh#L515-L516.

To use this, we should create a hack/release.sh script with a build_release() function. You can see how the kn client integrates with this here: https://github.com/knative/client/blob/main/hack/release.sh#L20-L28. It looks pretty straightforward, and I think we can do something similar rather than rely on release-please to generate the release. Instead, we can just use release-please to create a release PR and keep it current with CHANGELOG/version.txt updates. When we want to cut a release, we land the release PR, tag the release and manually create the version branch.

Summary

So roughly, here's my proposal... I think this should satisfy 1) 2) 3) 4) and 5).

• Continue using release-please to manage a release PR and CHANGELOG updates. But instead of doing this from a GitHub action on knative-sandbox/kn-plugin-func, do it either manually or as a periodic action in a fork repository.
• For a release, land the release PR
• Create a release-vX.Y.Z tag
• Create a vX.Y branch
• Run hack/release.sh somehow
• Update the release text to contain the body of the release PR - i.e. the CHANGELOG updates

Outstanding questions for me...

• How does hack/release.sh get executed? Who does that? Is it automated?
• Can we somehow make hack/release.sh scrape the release PR changes and apply these to the release it creates?
• It looks like hack/release.sh might actually create the tags and branches for us - does anyone have more complete documentation for this tooling than what I've found in the repo?
• How can I test all of this without having lots of messy tags and releases laying around?

[lkingland]

Seems rational to me so far, though I share most of the questions.

We currently have a bit of a central point from which to issue commands in the Makefile. I could see perhaps adding a new entry make release:

>  make help
make help
Usage: make <OPTIONS> ... <TARGETS>

Available targets are:

Usage:
  make <target>

Development
  build            (default) Build binary for current OS
  test             Run core unit tests
  check            Check code quality (lint)
  clean            Remove generated artifacts such as binaries and schemas

Templates
  test-templates   Run all template tests
  test-go          Test Go templates
  test-node        Test Node templates
  test-python      Test Python templates
  test-quarkus     Test Quarkus templates
  test-rust        Test Rust templates
  test-typescript  Test Typescript templates

Extended Testing (cluster required)
  test-integration  Run integration tests using an available cluster.
  test-e2e         Run end-to-end tests using an available cluster.

Releasing
  release          NEW!  Create a new release
  cross-platform   Build all distributable (cross-platform) binaries
  darwin           Build for Darwin (macOS)
  linux            Build for Linux
  windows          Build for Windows

Schemas
  schema-generate  Generate func.yaml schema
  schema-check     Check that func.yaml schema is up-to-date

This could be the starting point from which the process kicks off, manually if necessary, but it would be nice to retain the running automatically-updating PR if we can.

[lance]

This could be the starting point from which the process kicks off, manually if necessary, but it would be nice to retain the running automatically-updating PR if we can.

With release-please-action the PR is updated each time code lands on main. Obviously, if we are instead using the CLI from a fork, this won't work. It is possible, however, to schedule a regular action on a fork. WDYT about an hourly check/update?