From fb1f210bb8b567a6e70d74b15a5f1297b0888351 Mon Sep 17 00:00:00 2001 From: David Sherret Date: Sat, 6 Aug 2022 09:45:34 -0400 Subject: [PATCH] chore: use gist for release instruction checklist (#15414) --- .github/workflows/start_release.yml | 52 +++++++ tools/cut_a_release.md | 201 +------------------------ tools/release/00_start_release.ts | 49 +++++++ tools/release/release_doc_template.md | 204 ++++++++++++++++++++++++++ 4 files changed, 311 insertions(+), 195 deletions(-) create mode 100644 .github/workflows/start_release.yml create mode 100644 tools/release/00_start_release.ts create mode 100644 tools/release/release_doc_template.md diff --git a/.github/workflows/start_release.yml b/.github/workflows/start_release.yml new file mode 100644 index 0000000000..75d76a3f32 --- /dev/null +++ b/.github/workflows/start_release.yml @@ -0,0 +1,52 @@ +name: start_release + +on: + workflow_dispatch: + inputs: + releaseKind: + description: 'Kind of release' + default: 'patch' + type: choice + options: + - patch + - minor + - major + required: true + +jobs: + build: + name: start release + runs-on: ubuntu-20.04-xl + timeout-minutes: 30 + + env: + CARGO_TERM_COLOR: always + RUST_BACKTRACE: full + RUSTC_FORCE_INCREMENTAL: 1 + + steps: + - name: Configure git + run: | + git config --global core.symlinks true + git config --global fetch.parallel 32 + + - name: Clone repository + uses: actions/checkout@v2 + with: + token: ${{ secrets.DENOBOT_PAT }} + submodules: recursive + + - uses: dtolnay/rust-toolchain@stable + + - name: Install deno + uses: denoland/setup-deno@v1 + with: + # use a recent version instead of the latest version in case + # the latest version ever has issues that breaks publishing + deno-version: v1.23.2 + + - name: Run start release + env: + GITHUB_TOKEN: ${{ secrets.DENOBOT_PAT }} + GH_WORKFLOW_ACTOR: ${{ github.actor }} + run: ./tools/release/00_start_release.ts --${{github.event.inputs.releaseKind}} diff --git a/tools/cut_a_release.md b/tools/cut_a_release.md index 7ac1780410..47ecf2926f 100644 --- a/tools/cut_a_release.md +++ b/tools/cut_a_release.md @@ -1,197 +1,8 @@ # Cutting a Deno release -## Pre-flight checklist - -- [ ] An up to date stable Rust toolchain -- [ ] A binary version of `deno` available (hopefully built from `main`) that is - going to be available throughout any local building you might do. -- [ ] Forks and local clones of - [`denoland/deno`](https://github.com/denoland/deno/), - [`denoland/deno_std`](https://github.com/denoland/deno_std/), - [`denoland/dotland`](https://github.com/denoland/dotland/), - [`denoland/docland`](https://github.com/denoland/docland/), - [`denoland/deno_docker`](https://github.com/denoland/deno_docker/) - [`denoland/manual`](https://github.com/denoland/manual/) -- [ ] Ensure that external dependencies are up-to date in `denoland/deno` (e.g. - `rusty_v8`, `serde_v8`, `deno_doc`, `deno_lint`). -- [ ] Lot's of ☕ - -**During this process `main` branch (or any other branch that you're creating -release from) should be frozen and no commits should land until the release is -cut.** - -Before starting the process write a message in company's #general channel: -`:lock: deno and deno_std are now locked` - -## Updating `deno_std` - -1. Go to the "version_bump" workflow in the deno_std repo's actions: - https://github.com/denoland/deno_std/actions/workflows/version_bump.yml - -2. Click on the "Run workflow" button. - 1. For the kind of release, select "minor". - 2. Run the workflow. - -3. A PR will be automatically created. Follow the checklist in the PR and review - it. - -
- ❌ Failure Steps - - 1. Checkout the latest main. - 2. Manually run `./_tools/release/01_bump_version.ts --minor` - 1. Ensure the version in `version.ts` is updated correctly. - 2. Ensure `Releases.md` is updated correctly. - 3. Ensure all the tests pass with the latest build (examine the repo for - what the command is and run the local built deno binary) - 3. Open a PR with the changes and continue with the steps below. -
- -4. Merge the PR. - -5. Wait for the CI run to complete which will tag the repo and create a draft - release. Review the draft release and then publish it. - -
- ❌ Failure Steps - - 1. Tag the repo manually in the format `x.x.x` - 2. Draft a new GH release by copying and pasting the release notes from - `Releases.md` -
- -## Updating the main repo - -**If you are cutting a patch release**: First you need to sync commit to the -relevant minor branch, so if you are cutting a `v1.17.3` release you need to -sync `v1.17` branch. - -To do that, you need to cherry-pick commits from the main branch to the `v1.17` -branch. For patch releases we want to cherry-pick all commits that do not add -features to the CLI. This generally means to filter out `feat` commits but not -necessarily (ex. `feat(core): ...`). Check what was the last commit on `v1.17` -branch before the previous release and start cherry-picking newer commits from -the `main`. - -Once all relevant commits are cherry-picked, push the branch to the upstream and -verify on GitHub that everything looks correct. - -### Phase 1: Bumping versions - -1. After releasing deno_std, go to the "version_bump" workflow in the CLI repo's - actions: https://github.com/denoland/deno/actions/workflows/version_bump.yml - -2. Click on the "Run workflow" button. - 1. In the drop down, select the minor branch if doing a patch release or the - main branch if doing a minor release. - 2. For the kind of release, select either "patch", "minor", or "major". - 3. Run the workflow. - -3. Wait for the workflow to complete and for a pull request to be automatically - opened. - -
- ❌ Failure Steps - - 1. Checkout the branch the release is being made on. - 2. Manually run `./tools/release/01_bump_crate_versions.ts` - 1. Ensure the crate versions were bumped correctly - 2. Ensure deno_std version was updated correctly in `cli/compat/mod.rs` - 3. Ensure `Releases.md` was updated correctly - 3. Open a PR with the changes and continue with the steps below. -
- -4. Review the pull request and make any necessary changes. - -5. Merge it. - -### Phase 2: Publish - -1. Go to the "cargo_publish" workflow in the CLI repo's actions: - https://github.com/denoland/deno/actions/workflows/cargo_publish.yml - -2. Run it on the same branch that you used before and wait for it to complete. - -
- ❌ Failure Steps - - 1. The workflow was designed to be restartable. Try restarting it. - 2. If that doesn't work, then do the following: - 1. Checkout the branch the release is occurring on. - 2. If `cargo publish` hasn't completed then run - `./tools/release/03_publish_crates.ts` - - Note that you will need access to crates.io so it might fail. - 3. If `cargo publish` succeeded and a release tag wasn't created, then - manually create and push one for the release branch with a leading `v`. -
- -3. This CI run create a tag which triggers a second CI run that publishes the - GitHub draft release. - - The CI pipeline will create a release draft on GitHub - (https://github.com/denoland/deno/releases). Update the draft with the - contents of `Releases.md` that you previously added. - -4. Upload Apple M1 build (`deno-aarch64-apple-darwin.zip`) to the release draft - and to https://console.cloud.google.com/storage/browser/dl.deno.land - - ``` - cargo build --release - cd target/release - zip -r deno-aarch64-apple-darwin.zip deno - ``` - -5. Publish the release on Github - -6. Run the - https://github.com/denoland/dotland/actions/workflows/update_versions.yml - workflow. - - This should open a PR. Review and merge it. - -
- ❌ Failure Steps - - 1. Update https://github.com/denoland/dotland/blob/main/versions.json - manually. - 2. Open a PR and merge. -
- -7. Push a new tag to [`manual`](https://github.com/denoland/manual). The tag - must match the CLI tag; you don't need to create dedicated commit for that - purpose, it's enough to tag the latest commit in that repo. - -8. For minor releases: make sure https://github.com/mdn/browser-compat-data has - been updated to reflect Web API changes in this release. Usually done ahead - of time by @lucacasonato. - -9. **If you are cutting a patch release**: a PR should have been automatically - opened that forwards the release commit back to main. If so, merge it. If not - and it failed, please manually create one. - -## Updating `doc.deno.land` - -This should occur after the Deno CLI is fully published, as the build script -queries the GitHub API to determine what it needs to change and update. - -1. Run the update_deno workflow in the docland repo on the main branch: - https://github.com/denoland/docland/actions/workflows/update_deno.yml - -2. This will open a PR. Review it and merge, which will trigger a deployment. - -
- ❌ Failure Steps - - 1. Checkout a new branch for docland (e.g. `git checkout -b deno_1.17.0`). - 2. Execute `deno task build` - 3. Commit changes and raise a PR on `denoland/docland`. - 4. Merging the approved PR will trigger deployment to Deploy of the updates. -
- -## Updating `deno_docker` - -1. Open a PR on the `deno_docker` repo that bumps the Deno version in all - Dockerfiles, the README and the example Dockerfile -2. Create a tag with the version number (_without_ `v` prefix). - -Write a message in company's #general channel: -`:unlock: deno and deno_std are now unlocked`. +1. Go to this workflow: + https://github.com/denoland/deno/actions/workflows/start_release.yml +1. Select the kind of release, then run the workflow. +1. In the "Run start release" step, look at the bottom of the output to get the + gist url. +1. Fork the gist, and follow the instructions. diff --git a/tools/release/00_start_release.ts b/tools/release/00_start_release.ts new file mode 100644 index 0000000000..6c0c555a0d --- /dev/null +++ b/tools/release/00_start_release.ts @@ -0,0 +1,49 @@ +#!/usr/bin/env -S deno run -A --lock=tools/deno.lock.json +// Copyright 2018-2022 the Deno authors. All rights reserved. MIT license. +import { DenoWorkspace } from "./deno_workspace.ts"; +import { $, createOctoKit, semver } from "./deps.ts"; + +$.logStep("Loading cli crate..."); +const workspace = await DenoWorkspace.load(); +const cliCrate = workspace.getCliCrate(); +const nextVersion = getNextVersion(semver.parse(cliCrate.version)!); + +$.logStep("Creating gist with instructions..."); +const octoKit = createOctoKit(); +const result = await octoKit.request("POST /gists", { + description: `Deno CLI v${nextVersion.toString()} release checklist`, + public: false, + files: { + "release_instructions.md": { + content: buildDenoReleaseInstructionsDoc(), + }, + }, +}); + +$.log("=============================================="); +$.log("Created gist with instructions!"); +$.log(""); +$.log(` ${result.url}`); +$.log(""); +$.log("Please fork the gist and follow the checklist."); +$.log("=============================================="); + +function getNextVersion(originalVersion: semver.SemVer) { + if (Deno.args.some((a) => a === "--patch")) { + return originalVersion.inc("patch"); + } else if (Deno.args.some((a) => a === "--minor")) { + return originalVersion.inc("minor"); + } else if (Deno.args.some((a) => a === "--major")) { + return originalVersion.inc("major"); + } else { + throw new Error("Missing argument"); + } +} + +function buildDenoReleaseInstructionsDoc() { + const currentDirPath = $.path.dirname($.path.fromFileUrl(import.meta.url)); + const templateText = Deno.readTextFileSync( + $.path.join(currentDirPath, "release_doc_template.md"), + ); + return `# Deno CLI ${nextVersion.toString()} Release Checklist\n\n${templateText}`; +} diff --git a/tools/release/release_doc_template.md b/tools/release/release_doc_template.md new file mode 100644 index 0000000000..9c8ee9ae1a --- /dev/null +++ b/tools/release/release_doc_template.md @@ -0,0 +1,204 @@ +## Pre-flight checklist + +- Forks and local clones of + [`denoland/deno`](https://github.com/denoland/deno/), + [`denoland/deno_std`](https://github.com/denoland/deno_std/), + [`denoland/dotland`](https://github.com/denoland/dotland/), + [`denoland/docland`](https://github.com/denoland/docland/), + [`denoland/deno_docker`](https://github.com/denoland/deno_docker/) + [`denoland/manual`](https://github.com/denoland/manual/) + +**During this process `main` branch (or any other branch that you're creating +release from) should be frozen and no commits should land until the release is +cut.** + +- [ ] Write a message in company's #cli channel: + `:lock: deno and deno_std are now locked ()` + +## Patch release preparation + +**If you are cutting a patch release**: First you need to sync commit to the +relevant minor branch in the `deno` repo, so if you are cutting a `v1.17.3` +release you need to sync `v1.17` branch. + +To do that, you need to cherry-pick commits from the main branch to the `v1.17` +branch. For patch releases we want to cherry-pick all commits that do not add +features to the CLI. This generally means to filter out `feat` commits but not +necessarily (ex. `feat(core): ...`). Check what was the last commit on `v1.17` +branch before the previous release and start cherry-picking newer commits from +the `main`. + +Once all relevant commits are cherry-picked, push the branch to the upstream and +verify on GitHub that everything looks correct. + +- ⛔ DO NOT create a `vx.xx.x`-like branch! You are meant to cherry pick to a + `vx.xx` branch. If you have accidentally created a `vx.xx.x`-like branch then + delete it as tagging the CLI will fail otherwise. + +- [ ] Unstable `feat` commits were merged. +- [ ] Internal API commits like `feat(core)` were merged. + +## Updating `deno_std` + +- [ ] Go to the "version_bump" workflow in the deno_std repo's actions: + https://github.com/denoland/deno_std/actions/workflows/version_bump.yml + 1. Click on the "Run workflow" button. + 1. For the kind of release, select "minor". + 1. Run the workflow. + +- [ ] A PR will be automatically created. Follow the checklist in the PR, review + it, and merge the PR. + - ⛔ DO NOT create a release tag manually. That will automatically happen. + +
+ ❌ Failure Steps + + 1. Checkout the latest main. + 2. Manually run `./_tools/release/01_bump_version.ts --minor` + 1. Ensure the version in `version.ts` is updated correctly. + 2. Ensure `Releases.md` is updated correctly. + 3. Ensure all the tests pass with the latest build (examine the repo for + what the command is and run the local built deno binary) + 3. Open a PR with the changes and continue with the steps below. +
+ +- Wait for the CI run to complete which will automatically tag the repo and + create a draft release. + - [ ] Review the draft release and then publish it. + +
+ ❌ Failure Steps + + 1. Tag the repo manually in the format `x.x.x` + 2. Draft a new GH release by copying and pasting the release notes from + `Releases.md` +
+ +## Updating `deno` + +### Phase 1: Bumping versions + +- [ ] After releasing deno_std, go to the "version_bump" workflow in the CLI + repo's actions: + https://github.com/denoland/deno/actions/workflows/version_bump.yml + 1. Click on the "Run workflow" button. + 1. In the drop down, select the minor branch if doing a patch release or the + main branch if doing a minor release. + 1. For the kind of release, select either "patch", "minor", or "major". + 1. Run the workflow. + +- [ ] Wait for the workflow to complete and for a pull request to be + automatically opened. Review the pull request, make any necessary changes, + and merge it. + - ⛔ DO NOT create a release tag manually. + +
+ ❌ Failure Steps + + 1. Checkout the branch the release is being made on. + 2. Manually run `./tools/release/01_bump_crate_versions.ts` + 1. Ensure the crate versions were bumped correctly + 2. Ensure deno_std version was updated correctly in `cli/compat/mod.rs` + 3. Ensure `Releases.md` was updated correctly + 3. Open a PR with the changes and continue with the steps below. +
+ +### Phase 2: Publish + +- [ ] Go to the "cargo_publish" workflow in the CLI repo's actions: + https://github.com/denoland/deno/actions/workflows/cargo_publish.yml + 1. Run it on the same branch that you used before and wait for it to complete. + +
+ ❌ Failure Steps + + 1. The workflow was designed to be restartable. Try restarting it. + 2. If that doesn't work, then do the following: + 1. Checkout the branch the release is occurring on. + 2. If `cargo publish` hasn't completed then run + `./tools/release/03_publish_crates.ts` + - Note that you will need access to crates.io so it might fail. + 3. If `cargo publish` succeeded and a release tag wasn't created, then + manually create and push one for the release branch with a leading `v`. +
+ +- [ ] This CI run create a tag which triggers a second CI run that publishes the + GitHub draft release. + + The CI pipeline will create a release draft on GitHub + (https://github.com/denoland/deno/releases). Update the draft with the + contents of `Releases.md` that you previously added. + +- [ ] Upload Apple M1 build (`deno-aarch64-apple-darwin.zip`) to the release + draft and to https://console.cloud.google.com/storage/browser/dl.deno.land + + ``` + cargo build --release + cd target/release + zip -r deno-aarch64-apple-darwin.zip deno + ``` + +- ⛔ Verify that: + - [ ] There are 8 assets on the release draft. + - [ ] There are 4 zip files for this version on dl.deno.land + - [ ] The aarch64 Mac build was built from the correct branch AFTER the + version bump and has the same version as the release when doing + `deno -V` (ask someone with an M1 Mac to verify this if you don't have + one). + +- [ ] Publish the release on Github + +- [ ] Run the + https://github.com/denoland/dotland/actions/workflows/update_versions.yml + workflow. + - [ ] This should open a PR. Review and merge it. + +
+ ❌ Failure Steps + + 1. Update https://github.com/denoland/dotland/blob/main/versions.json + manually. + 2. Open a PR and merge. +
+ +- [ ] Push a new tag to [`manual`](https://github.com/denoland/manual). The tag + must match the CLI tag; you don't need to create dedicated commit for that + purpose, it's enough to tag the latest commit in that repo. + +- [ ] For minor releases: make sure https://github.com/mdn/browser-compat-data + has been updated to reflect Web API changes in this release. Usually done + ahead of time by @lucacasonato. + +- [ ] **If you are cutting a patch release**: a PR should have been + automatically opened that forwards the release commit back to main. If so, + merge it. If not and it failed, please manually create one. + +## Updating `doc.deno.land` + +This should occur after the Deno CLI is fully published, as the build script +queries the GitHub API to determine what it needs to change and update. + +- [ ] Run the update_deno workflow in the docland repo on the main branch: + https://github.com/denoland/docland/actions/workflows/update_deno.yml + - This will open a PR. Review it and merge, which will trigger a deployment. + +
+ ❌ Failure Steps + + 1. Checkout a new branch for docland (e.g. `git checkout -b deno_1.17.0`). + 2. Execute `deno task build` + 3. Commit changes and raise a PR on `denoland/docland`. + 4. Merging the approved PR will trigger deployment to Deploy of the updates. +
+ +## Updating `deno_docker` + +- [ ] Open a PR on the `deno_docker` repo that bumps the Deno version in all + Dockerfiles, the README and the example Dockerfile. Get it reviewed and + merge it. +- [ ] Create a tag with the version number (_without_ `v` prefix). + +## All done! + +- [ ] Write a message in company's #general channel: + `:unlock: deno and deno_std are now unlocked`.