From ac4980e0d73e79bbd13169ea05c43cfefff689fd Mon Sep 17 00:00:00 2001 From: eleanorjboyd <26030610+eleanorjboyd@users.noreply.github.com> Date: Wed, 2 Sep 2026 08:32:04 -0700 Subject: [PATCH 1/2] Document stable and point release process Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 1 + docs/releasing.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 80 insertions(+) create mode 100644 docs/releasing.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 042243b95..b78a291de 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -98,6 +98,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope ## Additional Resources - [Development Process](https://github.com/Microsoft/vscode-python/blob/main/CONTRIBUTING.md#development-process) +- [Release Process](./docs/releasing.md) - [API Documentation](./src/api.ts) - [Project Documentation](./docs/projects-api-reference.md) diff --git a/docs/releasing.md b/docs/releasing.md new file mode 100644 index 000000000..c955de28b --- /dev/null +++ b/docs/releasing.md @@ -0,0 +1,79 @@ +# Release process + +Python Environments uses even minor versions for stable releases and odd minor +versions for pre-release development. For example, `1.38.0` is a stable release +and `1.39.0` starts the next pre-release cycle. + +## Prepare the release branch + +Complete these steps before release day: + +1. Create a pull request against `main` that updates the version in + `package.json` and `package-lock.json` to the next even minor version: + + ```bash + npm version 1.38.0 --no-git-tag-version + ``` + +2. Merge the version-bump pull request into `main`. +3. Create the release branch from the updated `main` branch. Name it + `release/1..0`, for example `release/1.38.0`, and push it to the + upstream repository. +4. Create a second pull request against `main` that updates `package.json` and + `package-lock.json` to the next odd minor version: + + ```bash + npm version 1.39.0 --no-git-tag-version + ``` + +5. Merge the pre-release version-bump pull request into `main`. Do not merge + this change into the release branch. + +The release branch must therefore retain the even version while `main` moves +back to an odd pre-release version. + +## Publish on release day + +1. Run the stable Azure Pipelines build defined by + `build/azure-pipeline.stable.yml`. +2. Select the prepared release branch, for example `release/1.38.0`. +3. Set the **Publish Extension** parameter to `true`. +4. Monitor the build until publishing completes. +5. Verify that the extension is available in the Marketplace and that the + corresponding GitHub tag and release were created. The stable pipeline + automatically generates and publishes the GitHub release notes. + +## Publish a point release + +Use the existing release branch for a patch to a stable release. For example, +release `1.38.1` from `release/1.38.0`; do not create a +`release/1.38.1` branch. + +1. Apply the required fixes to the existing release branch. If a fix was first + merged into `main`, cherry-pick the relevant commit onto a branch created + from the release branch. +2. On that branch, update the version in `package.json` and + `package-lock.json` to the new patch version: + + ```bash + npm version 1.38.1 --no-git-tag-version + ``` + +3. Create and merge a pull request targeting the existing release branch, for + example `release/1.38.0`. +4. On release day, run the stable Azure Pipelines build from that release + branch with **Publish Extension** set to `true`. +5. Verify the Marketplace publication and the automatically generated GitHub + tag and release notes for the point release. + +Do not change the version on `main` as part of the point release. It should +remain on the odd minor version for the current pre-release development cycle. + +## Python environment tools dependency + +The branch named in the stable pipeline's `DownloadPipelineArtifact` step, such +as `refs/heads/release/2026.12`, belongs to the external Python environment +tools build. It is separate from this repository's `release/1..0` +branch. Before a stable release, verify that the configured tools branch is the +one intended for that release; update it in a separate pull request when the +tools release changes. From ee95013cebea9dfaed897b7d91e700a4eceeb5ff Mon Sep 17 00:00:00 2001 From: eleanorjboyd <26030610+eleanorjboyd@users.noreply.github.com> Date: Wed, 2 Sep 2026 15:00:25 -0700 Subject: [PATCH 2/2] Simplify release version bump steps Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/releasing.md | 43 ++++++++++++++----------------------------- 1 file changed, 14 insertions(+), 29 deletions(-) diff --git a/docs/releasing.md b/docs/releasing.md index c955de28b..81e1a1b02 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -8,26 +8,18 @@ and `1.39.0` starts the next pre-release cycle. Complete these steps before release day: -1. Create a pull request against `main` that updates the version in - `package.json` and `package-lock.json` to the next even minor version: - - ```bash - npm version 1.38.0 --no-git-tag-version - ``` - -2. Merge the version-bump pull request into `main`. -3. Create the release branch from the updated `main` branch. Name it +1. Change the version in `package.json` to the next even minor version, for + example `1.38.0`. +2. Run `npm i` to update `package-lock.json`. +3. Create and merge a pull request against `main`. +4. Create the release branch from the updated `main` branch. Name it `release/1..0`, for example `release/1.38.0`, and push it to the upstream repository. -4. Create a second pull request against `main` that updates `package.json` and - `package-lock.json` to the next odd minor version: - - ```bash - npm version 1.39.0 --no-git-tag-version - ``` - -5. Merge the pre-release version-bump pull request into `main`. Do not merge - this change into the release branch. +5. Change the version in `package.json` to the next odd minor version, for + example `1.39.0`. +6. Run `npm i` to update `package-lock.json`. +7. Create and merge a second pull request against `main`. Do not merge this + change into the release branch. The release branch must therefore retain the even version while `main` moves back to an odd pre-release version. @@ -49,17 +41,10 @@ Use the existing release branch for a patch to a stable release. For example, release `1.38.1` from `release/1.38.0`; do not create a `release/1.38.1` branch. -1. Apply the required fixes to the existing release branch. If a fix was first - merged into `main`, cherry-pick the relevant commit onto a branch created - from the release branch. -2. On that branch, update the version in `package.json` and - `package-lock.json` to the new patch version: - - ```bash - npm version 1.38.1 --no-git-tag-version - ``` - -3. Create and merge a pull request targeting the existing release branch, for +1. Change the version in `package.json` to the new patch version, for example + `1.38.1`. +2. Run `npm i` to update `package-lock.json`. +3. Create and merge a pull request against the existing release branch, for example `release/1.38.0`. 4. On release day, run the stable Azure Pipelines build from that release branch with **Publish Extension** set to `true`.