Release-Plan

Appearance

Getting Started ​

Automated ​

Use create-release-plan-setup, see the README over there for detailed instructions.

If you already have a local GITHUB_AUTH token,

bash
npx create-release-plan-setup@latest

does all the setup for you (aside from repo-configuration (see here))

how to get a GITHUB_AUTH token

You can create a GitHub personal access token here

Or, if you use the gh CLI, you can temporarily expose a token to your local terminal shell via:

bash
export GITHUB_AUTH=$(gh auth token);

This command will create

txt
.github/workflows/
  - plan-release.yml
  - publish.yml
RELEASE.md

which is responsible for automating the process that you'd run through manually below.

Manual ​

bash
npm i --save-dev release-plan
bash
pnpm add -D release-plan
bash
yarn add -D release-plan

To use release-plan you need to have a valid GITHUB_AUTH environment variable that has the repo permission. This allows release-plan to check what PRs have been merged since the last release and plan the release accordingly.

For new repositories or those without any tags, release-plan also requires an initial tag, we recommend:

bash
git tag v0.0.0
git push origin v0.0.0

  1. Run npx release-plan explain-plan. If there are unlabeled PRs that need to be released it will complain and show you a list of them. Each PR needs to be labeled with one of:

    • breaking
    • enhancement
    • bug
    • documentation
    • internal

  2. Once all the PRs are labeled, release-plan will instead show you the release plan, explaining which packages are getting released, at which versions, and why.

  3. If you disagree with the plan, you can modify the list of changes before using it to explain-plan or prepare a release:

    • npx release-plan gather-changes > /tmp/changelog
    • edit /tmp/changelog
    • npx release-plan --from-stdin < /tmp/changelog

    For example, this can be necessary if a PR that's labeled breaking touches multiple packages and only one of those packages is actually a breaking change. In that case you can take the other package names out of the description of the PR.

  4. Once you're happy with the plan, run npx release-plan prepare. This will edit CHANGELOG.md, bump the version numbers in package.json files, and create a file named .release-plan.json. Make a PR with these changes.

  5. Once the PR is merged, in a clean local repo at the merge commit, run npx release-plan publish. If you need an otp for your release you can provide that to the publish command like this npx release-plan publish --otp=123456