metamask / action-create-release-pr

MetaMask/action-create-release-pr

Description

This action creates a new release branch and PR. It also makes a commit that includes any release preparation that can be easily automated, which includes version bumps and a partial changelog updates (using @metamask/auto-changelog).

This action is only tested with Yarn v1.

Monorepos

This action is compatible with monorepos, but only if they use workspaces. It uses the workspaces property of package.json to determine if the repo is a monorepo, and to find each workspace.

The release type and git history determine which packages are bumped. For major releases, all packages are bumped. But for minor and patch releases, the git history will be scanned to determine whether each package has changed since the previous version. Only packages with changes since the previous version will be bumped.

This action uses a synchronized versioning strategy, meaning that the version of the root package.json file will be set on any updated packages. Packages in the monorepo may fall behind in version if they don't have any changes, but they'll jump directly to the current version of the entire monorepo if they change at all. As a result, the version change for individual packages might be beyond what SemVer would recommend. For example, packages might get major version bumps despite having no breaking changes. This is unfortunate, but for us the benefits of this simplified versioning scheme outweigh the harms.

Adding New Packages

In order for this action to continue working after new packages have been added to a monorepo with previously released packages, simply make the following changes to the new package:

1. Set the version field in its package.json to the version of the most recently released package in the monorepo.
2. Run yarn auto-changelog init in the root directory of the new package.

Usage

This Action can be used on its own, but we recommend using it with MetaMask/action-publish-release.

In order for this action to run, the project must have a Keep a Changelog-compatible changelog, even if it's empty. You should use @metamask/auto-changelog to do this.

You must add the Create Release Pull Request Workflow (or something equivalent) to use this action. Depending on the review processes of your organization, you may also want to add the Require Additional Reviewer Workflow.

Create Release Pull Request Workflow

Add the workflow file referenced below to your repository in the path .github/workflows/create-release-pr.yml. You'll notice that the workflow is manually triggered using the workflow_dispatch event. Once you've added the workflow file, you trigger the workflow via the Actions tab of the GitHub Web UI or the gh CLI.

A release-branch-prefix input must be specified to the Action, which will be used as the prefix for the names of release PR branches. The SemVer version being released is appended to the prefix. The default prefix is release/, which creates branches named e.g. release/1.0.0.

If this Action is used with MetaMask/action-publish-release, both Actions must be configured to use the same branch prefix. Their branch prefix defaults are the same within major versions.

• .github/workflows/create-release-pr.yml _ This workflow file self-references this action with the string "/.". Replace that string with "MetaMask/action-create-release-pr@v1" in your workflow.

Contributing

Setup

• Install Node.js version 18
  • If you are using nvm (recommended) running nvm use will automatically choose the right node version for you.
• Install Yarn v1
• Run yarn setup to install dependencies and run any requried post-install scripts
  • Warning: Do not use the yarn / yarn install command directly. Use yarn setup instead. The normal install command will skip required post-install scripts, leaving your development environment in an invalid state.

Testing and Linting

Run yarn test to run the tests once. To run tests on file changes, run yarn test:watch.

Run yarn lint to run the linter, or run yarn lint:fix to run the linter and fix any automatically fixable issues.

Releasing

The project follows the same release process as the other GitHub Actions in the MetaMask organization. The GitHub Actions action-create-release-pr and action-publish-release are used to automate the release process; see those repositories for more information about how they work.

1. Choose a release version.

   • The release version should be chosen according to SemVer. Analyze the changes to see whether they include any breaking changes, new features, or deprecations, then choose the appropriate SemVer version. See the SemVer specification for more information.

2. If this release is backporting changes onto a previous release, then ensure there is a major version branch for that version (e.g. 1.x for a v1 backport release).

   • The major version branch should be set to the most recent release with that major version. For example, when backporting a v1.0.2 release, you'd want to ensure there was a 1.x branch that was set to the v1.0.1 tag.

3. Trigger the workflow_dispatch event manually for the Create Release Pull Request action to create the release PR.

   • For a backport release, the base branch should be the major version branch that you ensured existed in step 2. For a normal release, the base branch should be the main branch for that repository (which should be the default value).
   • This should trigger the action-create-release-pr workflow to create the release PR.

4. Update the changelog to move each change entry into the appropriate change category (See here for the full list of change categories, and the correct ordering), and edit them to be more easily understood by users of the package.

   • Generally any changes that don't affect consumers of the package (e.g. lockfile changes or development environment changes) are omitted. Exceptions may be made for changes that might be of interest despite not having an effect upon the published package (e.g. major test improvements, security improvements, improved documentation, etc.).
   • Try to explain each change in terms that users of the package would understand (e.g. avoid referencing internal variables/concepts).
   • Consolidate related changes into one change entry if it makes it easier to explain.
   • Run yarn auto-changelog validate --rc to check that the changelog is correctly formatted.

5. Review and QA the release.

   • If changes are made to the base branch, the release branch will need to be updated with these changes and review/QA will need to restart again. As such, it's probably best to avoid merging other PRs into the base branch while review is underway.

6. Squash & Merge the release.

   • This should trigger the action-publish-release workflow to tag the final release commit and publish the release on GitHub. Since this repository is a GitHub Action, this completes the release process.
     • Note that the shorthand major version tag is automatically updated when the release PR is merged. See publish-release.yml for details.

action-create-release-pr's Issues

Develop command-line tool based on this action

Currently, this action makes a set of changes that are needed to create a new release and groups those changes into a branch/PR. For convenience we call these changes a "release candidate", and in order to create a release candidate, two things must happen:

1. The root package should be bumped along with any packages that have changed since the previous release.
2. The changelog should be updated with the commits that will be included in the new release.

We want to change the process of releasing a monorepo such that:

1. When bumping packages, versions are no longer synchronized with the root package.
2. Each package gets its own changelog, so each package's changelog should be updated accordingly.

To accommodate this, we want to turn this action into a command-line tool. This tool should work for both monorepos and polyrepos. This likely means we need to create a new repo to hold this tool, but I am creating this issue here for convenience.

Monorepos

For a particular monorepo, when the developer runs this tool, it should list all packages matched by the root package's workspaces property that have been updated since the last tag of the monorepo. This prompt should allow the developer to select which packages should be bumped and how (major, minor, patch, exact version).

For each package the developer has selected, the tool should then look at the commits made since the last published release of the package that change any part of the package and add those commits under a new section within the package's changelog that is headered by the new version selected for that package.

Polyrepos

The command-line tool should also work for polyrepos as well. In this case, there is no need to list multiple packages; all that is required is to ask for how the root package should be bumped (major, minor, patch, exact version).

The tool should then look at the commits made since the last published release of the package and add those commits under a new section within the package's changelog that is headered by the new version selected for that package.

Shellcheck linting

We should add ShellCheck (a linter for shell scripts) to CI, to improve the quality of our scripts and prevent mistakes and dangerous patterns.

We use it on the extension with this CircleCI job. We should be able to find an equivalent GitHub action, or write one if necessary.

Consider adding a default entry for empty changelog release entries in monorepos

Currently, if a monorepo package is released during a major version bump but hasn't changed, the changelog is by default empty. We should consider adding some kind of default so as to not confuse readers.

Should create/update CHANGELOG.md

Automate updating latest major version tag for each release

As a convenience, maintainers of popular actions (e.g. actions/checkout) maintain a shorthand major version tag (e.g. v1) that points to the latest major version release. We recommend using this same shorthand for our release automation actions, but the tag has to be updated manually. We should automate the updating of this tag, which ought to be simple enough.

This action should be triggered and receive inputs via workflow_dispatch

We should follow the example of MetaMask/action-monorepo-release-pr.

on:
    workflow_dispatch:
        inputs:
            release-type:
                description: 'A SemVer version diff, i.e. major, minor, patch, prerelease etc. Mutually exclusive with "release-version".'
                required: false
            release-version:
                description: 'A specific version to bump to. Mutually exclusive with "release-type".'
                required: false

Enable ignoring tags

Currently, this action fails if tag validation fails, including if the most recent tag is not a valid SemVer version. We should add a configurable tag ignore list, probably via an action input, maybe using globs.

Show changelog in release PR description

It would be helpful to show the changelog in the release PR description, to help the reviewers understand what has changed in the release. We could embed the entire changelog contents for the current release, or we could do something simpler like link the section of the changelog for the current release.

Fix monorepo version synchronization behavior

Currently, this action "synchronizes" package versions in monorepos (i.e., updates the version of all monorepo packages wherever they appear as dependencies in this monorepo), for major releases only. This has often created problems for us, and we should consider making it always synchronize package versions or parameterize the behavior.

We need to keep two things in mind while making this change:

1. The most recent published versions of all packages should be compatible per SemVer
2. Packages should always be internally compatible in the monorepo
   • This is the rub, because if package versions become unsynchronized in the monorepo, yarn setup/ yarn install will install monorepo packages from the registry instead of linking the local versions. IIRC, there's some kind of setting (maybe in .yarnrc?) that forces yarn to always install from the monorepo, but I'm not sure. If that setting exists, we could just document that monorepos that use this action should enable it. Otherwise, we may just have to default to synchronizing versions.

Improve error when release branch already exists

If the release branch already exists, the action will fail with an error message that doesn't make it obvious why it failed. We should plainly state that the release branch already exists, and that it should be deleted to run the action.

Does not work on personal private repos due to "Draft" hub create release option

Using this on private personal repos errors:

pull request create failed: GraphQL error: Draft pull requests are not supported in this repository.

Their docs describe:

Draft pull requests are available in public repositories with GitHub Free for organizations and legacy per-repository billing plans, and in public and private repositories with GitHub Team, GitHub Enterprise Server 2.17+, and GitHub Enterprise Cloud

Source: https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests

Ideally this --draft should become optional via an input parameter

action-create-release-pr/scripts/create-release-pr.sh

Line 38 in 34e157f

--draft \

Prevent action initiators from merging their own pull requests

Because the author of the pull request is the GitHub Actions bot, the creator of the release pull request can also merge it. This is bad. (I am bad.)

The action initiator is identified by the github.actor context property (see this page) during workflow runs. We could instrument the action to make the action initiator the PR author, but that would require everyone to create and manage Personal Access Tokens. That would be bad.

A better solution, suggested by @Gudahtt, is to somehow identify the action initiator in the release PR itself, and use a second action as a mandatory check that only passes if someone other than the initiator approves the PR.

After some research, I believe that the best way to accomplish this is to use artifacts. Artifacts are specific to repositories, persisted to specified paths between workflow runs, and GitHub provides easy-to-use actions to upload and download them.

This action should, after creating the release PR, upload an artifact identified by some UID (e.g., the PR number), containing the string value of github.actor. We should then create a second action or workflow that downloads this artifact and only succeeds if someone other than the initiator of this action has approved the PR. GitHub deletes artifacts after 90 days by default, so cleanup shouldn't be necessary, but we can optionally delete the artifact in a third workflow when the PR is closed (pull_request, closed).

`dist/index.js` should be collapsed by default in diffs

dist/index.js is a generated file and creates noise in PRs. We should consider hiding this by default.