From 344da983c6cb38e0f1816b9fbf65a27a2accd0ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulises=20Gasc=C3=B3n?= Date: Fri, 1 Mar 2024 11:48:28 +0100 Subject: [PATCH] docs: update release process --- Release-Process.md | 262 +++++++++++++++++++++++++-------------------- 1 file changed, 147 insertions(+), 115 deletions(-) diff --git a/Release-Process.md b/Release-Process.md index ae740972f7..355ddc5b12 100644 --- a/Release-Process.md +++ b/Release-Process.md @@ -13,174 +13,206 @@ must have the following access permissions: ### 1. Github release access The individual making the release will need to be a member of the -expressjs/express team with Write permission level so they are able to tag the -release commit and push changes to the expressjs/express repository -(see Steps 4 and 5). +`expressjs/express` team with Write permission level so they are able to tag the +release commit and push changes to the `expressjs/express` repository ### 2. npmjs.com release access The individual making the release will need to be made an owner on the `express` package on npmjs.com so they are able to publish the release -(see Step 6). -## How to publish a release +### 3. GPG key -Before publishing, the following preconditions should be met: +The individual making the release will need to have a GPG key and have it added to their GitHub account. -- A release proposal issue or tracking pull request (see "Proposal branch" - below) will exist documenting: - - the proposed changes - - the type of release: patch, minor or major - - the version number (according to semantic versioning - http://semver.org) -- The proposed changes should be complete. +It is expected to sign the commits and tags with the GPG key. -There are two main release flows: patch and non-patch. +[More details](https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account) -The patch flow is for making **patch releases**. As per semantic versioning, -patch releases are for simple changes, eg: typo fixes, patch dependency updates, -and simple/low-risk bug fixes. Every other type of change is made via the -non-patch flow. -### Branch terminology +## How to publish a release -"Master branch" +Notes: -- There is a branch in git used for the current major version of Express, named - `master`. -- This branch contains the completed commits for the next patch release of the - current major version. -- Releases for the current major version are published from this branch. +- Version strings are listed below as "vx.y.z" or "x.y.z". Substitute for the release version. +- Examples will use the fictional release version 11.22.33. -"Version branch" +**Key considerations for security releases** -- For any given major version of Express (current, previous or next) there is - a branch in git for that release named `.x` (eg: `4.x`). -- This branch points to the commit of the latest tag for the given major version. +When preparing a security release, follow the instruction in [security-release.md] and not this guide. -"Release branch" +Security releases are a special case and should be handled with care. If you are +preparing a security release, you should follow the security steps in the details +sections. It is extremely important to avoid disclosing security vulnerabilities +before the release is available to the public, to avoid putting users at risk. -- For any given major version of Express, there is a branch used for publishing - releases. -- For the current major version of Express, the release branch is the - "Master branch" named `master`. -- For all other major versions of Express, the release branch is the - "Version branch" named `.x`. -"Proposal branch" +### 0. Pre-release steps -- A branch in git representing a proposed new release of Express. This can be a - minor or major release, named `.0` for a major release, - `.` for a minor release. -- A tracking pull request should exist to document the proposed release, - targeted at the appropriate release branch. Prior to opening the tracking - pull request the content of the release may have be discussed in an issue. -- This branch contains the commits accepted so far that implement the proposal - in the tracking pull request. +**Define the scope** +Before preparing a Express.js release, you should know: +- the potential proposed changes (eg: bug fixes, new features, etc) +- the type of release: patch, minor or major +- the version number (according to semantic versioning - http://semver.org) +- the release date expected (when the release will be available in npm). -### Patch flow +**Choosing a good date** -In the patch flow, simple changes are committed to the release branch which -acts as an ever-present branch for the next patch release of the associated -major version of Express. +Please avoid releasing on weekends or holidays as it may be difficult to get help if something goes wrong and also to avoid the need to work for the users that will need to update their applications. -The release branch is usually kept in a state where it is ready to release. -Releases are made when sufficient time or change has been made to warrant it. -This is usually proposed and decided using a github issue. +**Announce the release** -### Non-patch flow +You should notify the community of your +intent to release. This can be done by creating a message in the slack channel +`#express`. This is to ensure that the community is aware of the release and +can provide feedback if necessary. -In the non-patch flow, changes are committed to a temporary proposal branch -created specifically for that release proposal. The branch is based on the -most recent release of the major version of Express that the release targets. +**Prepare the environment** -Releases are made when all the changes on a proposal branch are complete and -approved. This is done by merging the proposal branch into the release branch -(using a fast-forward merge), tagging it with the new version number and -publishing the release package to npmjs.com. +It is expected that you will have a clean environment to prepare the release +and you should have a personal fork of the `expressjs/express` repository to push the +release branch to it. -### Flow -Below is a detailed description of the steps to publish a release. +### 1. Checkout the major branch and create the release proposal branch -#### Step 1. Check the release is ready to publish +Checkout the major branch locally. -Check any relevant information to ensure the release is ready, eg: any -milestone, label, issue or tracking pull request for the release. The release -is ready when all proposed code, tests and documentation updates are complete -(either merged, closed or re-targeted to another release). +```bash +git remote update +git checkout 11.x +git reset --hard upstream/11.x +``` -#### Step 2. (Non-patch flow only) Merge the proposal branch into the release branch +Create a new branch for the release proposal and push it. + +```bash +git checkout -b 11.22.33-proposal +git push origin 11.22.33-proposal +git push upstream 11.22.33-proposal +``` -In the patch flow: skip this step. -In the non-patch flow: -```sh -$ git checkout -$ git merge --ff-only +### 2. Cherry pick and backport the changes + +Cherry pick and backport the changes to the `11.22.33-proposal` branch +that you want to include in the release and then push the changes + +```bash +git cherry-pick -x +# repeat for each commit that you want to include in the release +git push origin 11.22.33-proposal +git push upstream 11.22.33-proposal ``` - - see "Release branch" of "Branches" above. - - see "Proposal branch" of "Non-patch flow" above. -**NOTE:** You may need to rebase the proposal branch to allow a fast-forward - merge. Using a fast-forward merge keeps the history clean as it does - not introduce merge commits. +### 3. Update the metadata and the changelog -### Step 3. Update the History.md and package.json to the new version number -The changes so far for the release should already be documented under the -"unreleased" section at the top of the History.md file, as per the usual -development practice. Change "unreleased" to the new release version / date. -Example diff fragment: +Update the `History.md` and `package.json` files with the new version and the changes and commit it. -```diff --unreleased --========== -+4.13.3 / 2015-08-02 -+=================== + +```bash +git commit -S -m "11.22.33" ``` -The version property in the package.json should already contain the version of -the previous release. Change it to the new release version. +Push the changes to the release branch -Commit these changes together under a single commit with the message set to -the new release version (eg: `4.13.3`): +```bash +git push origin 11.22.33-proposal +git push upstream 11.22.33-proposal +``` -```sh -$ git checkout -<..edit files..> -$ git add History.md package.json -$ git commit -m '' +### 4. Create a pull request with the release proposal + +Create a pull request with the release proposal branch and assign the Repo captains and TC Team to review it. You will target the major version branch (eg: `11.x`) from your personal fork. + +If the CI tests are not passing, please fix the issues and update the pull request with the new changes, you can leave the PR in draft mode until the CI tests are passing. + +**Important:** if the release has changed you will need to update the files and amend the commit. Add the tag release + +You can use [this PR](https://github.com/expressjs/express/pull/5505) as a reference + +### 4. Land the release proposal + +Once the pull request is approved, you can land it to the major branch (e.g. `v11.x`) branch. + +```bash +git checkout 11.22.33-proposal +git rebase 11.x +git checkout 11.x +git merge --ff-only 11.22.33-proposal +git push ``` -### Step 4. Identify and tag the release commit with the new release version +**Important:** a release proposal is approved once the pull request was approved by at least one of the Repo captains or a TC Member and has passed 72h since the PR was opened. + +Note: The Pull Request will be closed automatically when the release proposal is merged. -Create a lightweight tag (rather than an annotated tag) named after the new -release version (eg: `4.13.3`). +### 5. Tag the release -```sh -$ git tag +Tag the release from your release branch (e.g. `11.22.33-proposal`) with the same version number + +```bash +git checkout 11.22.33-proposal +git tag 11.22.33 --sign --message "11.22.33" ``` -### Step 5. Push the release branch changes and tag to github +### 6. Push the tag + +8. Push the tag to the repository, (e.g.`11.22.33`) +```bash +git push origin 11.22.33 +git push upstream 11.22.33 +``` + +### 7. Publish the release + +Create a new release on GitHub using the tag (e.g. https://github.com/UlisesGascon/express/releases/new?tag=11.22.33) use https://github.com/expressjs/express/releases/tag/4.18.3 as an example for title and content format. We can use the `History.md` content has the `Main Changes` section, the other sections are autopopulated when clicking on "Generate Release Notes". -The branch and tag should be pushed directly to the main repository -(https://github.com/expressjs/express). +### 8. Publish to npm -```sh -$ git push origin -$ git push origin +This is the most critical step as you won't be able to unpublish the release if something goes wrong. So please double-check everything before publishing. + +Check the package content: + +```bash +npm publish --dry-run ``` -### Step 6. Publish to npmjs.com +When you are ready to publish, run: + +```bash +npm publish +``` -Ensure your local working copy is completely clean (no extra or changed files). -You can use `git status` for this purpose. +### 9. Update the release proposal PR -```sh -$ npm login -$ npm publish +Add a comment in the pull request with the confirmation of the release and the link to the release on GitHub and npm, (e.g. https://github.com/expressjs/express/pull/5505#issuecomment-1970980785) + +### 10. Clean up branches and prepare for the next release + +Push the release commit to `main` branch and manage the git conflicts if necessary. + +```bash +git checkout main +git reset --hard upstream/main +git cherry-pick 11.22.33-proposal +git push origin main +git push upstream main +``` + +Once the release is published, you can delete the release proposal branch and the tag from your local and remote repositories. + +```bash +git push origin --delete 11.22.33-proposal +git push upstream --delete 11.22.33-proposal ``` -**NOTE:** The version number to publish will be picked up automatically from - package.json. +### 11. Announce the release + +Promote the release on Slack (`#express` channel) and in social media (e.g [4.18.3](https://openjs-foundation.slack.com/archives/C02QB1731FH/p1709208390734159)). + +### 12. Celebrate it 🎉 + +**Congratulations!** You have successfully released a new version of Express.js. So now it's time to celebrate it _in whatever form you do this..._ \ No newline at end of file