From c9f9f62bc797d8c02c1061d2e21239c4b62cf62c Mon Sep 17 00:00:00 2001 From: Robert Date: Wed, 8 Nov 2023 12:38:26 +0000 Subject: [PATCH] Add instructions for releasing from a branch other than main --- docs/releasing.md | 86 ++++++++++++++++------------------------------- 1 file changed, 29 insertions(+), 57 deletions(-) diff --git a/docs/releasing.md b/docs/releasing.md index 574f58c24..4badcf202 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -1,80 +1,52 @@ # Releasing (write access required) -1. Run the ["Run CLI tests" workflow](https://github.com/github/vscode-codeql/actions/workflows/cli-test.yml) and make sure the tests are green. If there were no merges between the time the workflow ran (it runs daily), and the release, you can skip this step. +1. Determine the new version number. We default to increasing the patch version number, but make our own judgement about whether a change is big enough to warrant a minor version bump. Common reasons for a minor bump could include: + * Making substantial new features available to all users. This can include lifting a feature flag. + * Breakage in compatibility with recent versions of the CLI. + * Minimum required version of VS Code is increased. + * New telemetry events are added. + * Deprecation or removal of commands. + * Accumulation of many changes, none of which are individually big enough to warrant a minor bump, but which together are. This does not include changes which are purely internal to the extension, such as refactoring, or which are only available behind a feature flag. +1. Create a release branch named after the new version (e.g. `v1.3.6`): + * For a regular scheduled release this branch will be based on latest `main`. + * To do a minimal bug-fix release, base the release branch on the tag from the most recent release and then add only the changes you want to release. + * Choose this option if you want to release a specific set of changes (e.g. a bug fix) and don't want to incur extra risk by including other changes that have been merged to the `main` branch. +1. Run the ["Run CLI tests" workflow](https://github.com/github/vscode-codeql/actions/workflows/cli-test.yml) and make sure the tests are green. + * You can skip this step if you are releasing from `main` and there were no merges since the most recent daily scheduled run of this workflow. 1. Double-check the `CHANGELOG.md` contains all desired change comments and has the version to be released with date at the top. - * Go through all recent PRs and make sure they are properly accounted for. + * If releasing from `main`, go through PRs that have been merged since the previous release and make sure they are properly accounted for. + * If doing a minimal bug-fix release, the changelog will only contain the changes you're intending to release. * Make sure all changelog entries have links back to their PR(s) if appropriate. - * For picking the new version number, we default to increasing the patch version number, but make our own judgement about whether a change is big enough to warrant a minor version bump. Common reasons for a minor bump could include: - * Making substantial new features available to all users. This can include lifting a feature flag. - * Breakage in compatibility with recent versions of the CLI. - * Minimum required version of VS Code is increased. - * New telemetry events are added. - * Deprecation or removal of commands. - * Accumulation of many changes, none of which are individually big enough to warrant a minor bump, but which together are. This does not include changes which are purely internal to the extension, such as refactoring, or which are only available behind a feature flag. -1. Double-check that the node version we're using matches the one used for VS Code. See the [Node.js version instructions](./node-version.md) for more information. 1. Double-check that the extension `package.json` and `package-lock.json` have the version you intend to release. If you are doing a patch release (as opposed to minor or major version) this should already be correct. -1. Create a PR for this release: - * This PR will contain any missing bits from steps 1, 2 and 3. Most of the time, this will just be updating `CHANGELOG.md` with today's date. - * Create a new branch for the release named after the new version. For example: `v1.3.6` - * Create a new commit with a message the same as the branch name. - * Create a PR for this branch. - * Wait for the PR to be merged into `main` -1. Switch to `main` branch and pull latest changes -1. Lock the `main` branch. - * Go to the [branch protection rules for the `main` branch](https://github.com/github/vscode-codeql/settings/branch_protection_rules/16447115) - * Select "Lock branch" - * Click "Save changes" -1. Ensure that no PRs have been merged since the release PR that you merged. If there were, you might need to unlock `main` temporarily and update the CHANGELOG again. -1. Build the extension `npm run build` and install it on your VS Code using "Install from VSIX". +1. Commit any changes made during steps 4 and 5 with a commit message the same as the branch name (e.g. `v1.3.6`). +1. Open a PR for this release. + * The PR diff should contain: + * Any missing bits from steps 4 and 5. Most of the time, this will just be updating `CHANGELOG.md` with today's date. + * If releasing from a branch other than `main`, this PR will also contain the extension changes being released. +1. Build the extension using `npm run build` and install it on your VS Code using "Install from VSIX". 1. Go through [our test plan](./test-plan.md) to ensure that the extension is working as expected. -1. Switch to `main` and add a new tag on the `main` branch with your new version (named after the release), e.g. - +1. Create a new tag on the release branch with your new version (named after the release), e.g. ```bash - git checkout main git tag v1.3.6 ``` - - If you've accidentally created a badly named tag, you can delete it via - - ```bash - git tag -d badly-named-tag - ``` - -1. Unlock the main branch - * Go to the [branch protection rules for the `main` branch](https://github.com/github/vscode-codeql/settings/branch_protection_rules/16447115) - * Deselect "Lock branch" - * Click "Save changes" +1. Merge the release PR into `main`. + * The release PR must be merged before pushing the tag to ensure that we always release a commit that is present on the `main` branch. It's not required that the commit is the head of the `main` branch, but there should be no chance of a future release accidentally not including changes from this release. 1. Push the new tag up: - - a. If you're using a fork of the repo: - - ```bash - git push upstream refs/tags/v1.3.6 - ``` - - b. If you're working straight in this repo: - ```bash git push origin refs/tags/v1.3.6 ``` - - This will trigger [a release build](https://github.com/github/vscode-codeql/releases) on Actions. - - * **IMPORTANT** Make sure you are on the `main` branch and your local checkout is fully updated when you add the tag. - * If you accidentally add the tag to the wrong ref, you can just force push it to the right one later. -1. Monitor the status of the release build in the `Release` workflow in the Actions tab. +1. Find the [Release](https://github.com/github/vscode-codeql/actions?query=workflow%3ARelease) workflow run that was just triggered by pushing the tag, and monitor the status of the release build. * DO NOT approve the "publish" stages of the workflow yet. 1. Download the VSIX from the draft GitHub release at the top of [the releases page](https://github.com/github/vscode-codeql/releases) that is created when the release build finishes. 1. Unzip the `.vsix` and inspect its `package.json` to make sure the version is what you expect, or look at the source if there's any doubt the right code is being shipped. 1. Install the `.vsix` file into your vscode IDE and ensure the extension can load properly. Run a single command (like run query, or add database). -1. Go to the actions tab of the vscode-codeql repository and select the [Release workflow](https://github.com/github/vscode-codeql/actions?query=workflow%3ARelease). +1. Approve the deployments of the [Release](https://github.com/github/vscode-codeql/actions?query=workflow%3ARelease) workflow run. This will automatically publish to Open VSX and VS Code Marketplace. * If there is an authentication failure when publishing, be sure to check that the authentication keys haven't expired. See below. -1. Approve the deployments of the correct Release workflow. This will automatically publish to Open VSX and VS Code Marketplace. -1. Go to the draft GitHub release in [the releases tab of the repository](https://github.com/github/vscode-codeql/releases), click 'Edit', add some summary description, and publish it. -1. Confirm the new release is marked as the latest release at . +1. Go to the draft GitHub release in [the releases page](https://github.com/github/vscode-codeql/releases), click 'Edit', add some summary description, and publish it. +1. Confirm the new release is marked as the latest release. 1. If documentation changes need to be published, notify documentation team that release has been made. -1. Review and merge the version bump PR that is automatically created by Actions. +1. Review and merge the version bump PR that is automatically created by the Release workflow. ## Secrets and authentication for publishing