From fdd52b2032804eeafd9989a75fcff19bc0e36aeb Mon Sep 17 00:00:00 2001 From: Mariusz Nowak Date: Thu, 5 Dec 2019 13:12:50 +0100 Subject: [PATCH] docs: Document new release process --- RELEASE_PROCESS.md | 86 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 60 insertions(+), 26 deletions(-) diff --git a/RELEASE_PROCESS.md b/RELEASE_PROCESS.md index 18d92c570..bec25ffdf 100644 --- a/RELEASE_PROCESS.md +++ b/RELEASE_PROCESS.md @@ -1,51 +1,85 @@ -# Release Process +# Release process -This document contains all the necessary information about out release process. +## Semi-automation -### Merge freeze +Serverless Framework relies on [semantic commit messages](https://www.conventionalcommits.org/en/v1.0.0-beta.4/#summary) which allows to streamline the release process (versioning and changelog generation is automated) -A "merge freeze" will be applied a few days before the release. This means that **NOTHING** will be added to the release branch. +See proposed [Commit Message Guidelines](https://docs.google.com/document/d/1hKUs3qt_aVp_PBI1UqvfaIqKma3jAJimEoGCRGGbOqs/edit#) -A "merge freeze" ends once the release was published. +In PR's as coming from forks (community contributions) while its welcome, we do not require to follow semantic commit messages. Yet, such PR is expected to be squash merged by project member with a single semantic commit message. -## Different types of releases +PR's comming from branches have commit messages validated with [commmitlint](https://commitlint.js.org/#/) -**Note:** More about versioning can be found in our dedicated [VERSIONING file](https://github.com/serverless/serverless/blob/master/VERSIONING.md). +## Release flow -Releases can come in different flavors. Here's a list with the most common release types and how they're treated +Releases are triggered manually by preparing a release PRs -### Minor / Major release +### Regular minor releases -The minor / major release is a planned release which includes all the changes added since the last minor / major release (including bugfixes). The user should pick up the latest minor / major release automatically when installing / updating Serverless. +Contain new features, enhancements and non-critical bug fixes. Issued every two weeks -The minor / major releases is released at a pre-defined time. +#### Preparation steps: -#### Versioning / tagging +1. Create the `release` branch (should derive from current `master` state) +2. Bump version ranges of _all_ dependencies to latest supported versions (e.g. if latest version of a dependency is `2.3.5` and range in a `package.json` is `^2.2.4` then it should be updated to `^2.3.5`) + _Note: Unfortunately there seems no reliable utility to automate that (there's a [request at `npm-check-updates`](https://github.com/tjunnone/npm-check-updates/issues/581)) + If you handle installation of dependencies through [npm-cross-link](https://github.com/medikoo/npm-cross-link#npm-cross-link) then [`--bump-deps`](https://github.com/medikoo/npm-cross-link#general-options) option will bump version ranges as expected_ +3. Commit eventual dependency version updates with following commit message: + `chore: Bump dependencies` +4. Run `npm run prepare-release` command. + _It'll automatically bump version in `package.json` to expected one (by inspecting changes since previous release) and will generate new changelog entry._ +5. Improve generated changelog entry in `CHANGELOG.md`: -Assuming our current version is `v1.1.0`. + - Ensure to remove evenutal items that were already published with patch releases + - Improve formatting and messages if applicable + - Ensure that updated `CHANGELOG.md` follows prettier formatting -The minor release would be `v1.2.0`. The major release would be `v2.0.0`. +6. Commit `package.json` and `CHANGELOG.md` changes with following commit message: + `chore: Release` + **Note: For automation purpose it is important that it's the last commit in the PR** +7. Push branch upstream and create a PR. + _Release PR's are automatically detected in CI by fact of `version` in `package.json` file being changed in last commit. In context of that build, existence of new version changelog entry (in `CHANGELOG.md`) is validated._ +8. After PR is accepted by CI and one of the reviewers, merge it via _"Rebase and merge"_ option -### Patch release +_Further actions are automated in CI context:_ -Patch releases should **only** include critical bug fixes and released ASAP. The user should pick up the latest patch release automatically when installing / updating Serverless. +9. _`master` CI build detects that release PR was merged (by fact that it covers change of `version` field in `package.json` file). Having that (after successufl tests pass) version tag is created and pushed to the repository._ +10. _Tag CI build publishes new version to npm, also it retrieves release notes from CHANGELOG.md and publishes them to GitHub._ -#### Versioning / tagging +### Fast releases -Assuming our current version is `v1.1.0`. +Usually about important bug-fixes or features that we wish to release immediately. -The patch release would be `v1.1.1`. +Contrary to regular releases, they derive from `release-fast-track` branch (not `master`). -### Alpha release +`release-fast-track` branch is automatically updated to point released version right after it's published, that means that if release is held from `master`, **the `release-fast-track` history is rewritten**. -Alpha releases are created to have a sneak peek into the upcoming feature set of the new release. They're also used for pre-release QA / internal usage. +For that reason community PR's in all cases should be based against `master`. If we want to fast release a patch as proposed by a community. After it is merged into `master`, we need to cherry-pick it into a branch that derives from `release-fast-track` and prepare a release on top of that. -Alpha releases are not scheduled and can be pushed multiple times throughout a development phase. +#### Preparation steps: -Alpha releases should never be installed automatically when the user installs / updates Serverless. The user should be forced to explicitly name the alpha release during the installation / update phase (e.g. via `npm install --global serverless@alpha`). +1. Ensure that PR which contains a fix intended to be immediately published, derives from `release-fast-track` branch and is based against it. +2. Run `npm run prepare-release` command in context pf a PR branch + _It'll automatically bump version in `package.json` to expected one (by inspecting changes since previous release) and will generate new changelog entry._ +3. Improve generated changelog entry in `CHANGELOG.md`: -#### Versioning / tagging + - Improve formatting and messages if applicable + - If any updates were applied ensure that updated `CHANGELOG.md` follows prettier formatting -Assuming our current version is `v1.1.0`. +4. Commit `package.json` and `CHANGELOG.md` changes with following commit message: + `chore: Release` + **Note: For automation purpose it is important that it's the last commit in the PR** +5. After PR is accepted by CI and one of the reviewers, merge it via _"Rebase and merge"_ option -The alpha release would be `v1.2.0-alpha.1`. A subsequent alpha release would be `v1.2.0-alpha.2` etc. +_Further actions are automated in CI context:_ + +9. _`release-fast-track` CI build detects that release PR was merged (by fact that it covers change of `version` field in `package.json` file). Having that (after successful tests pass) version tag is created and pushed to the repository._ +10. _Tag CI build, publishes new version to npm, also it retrieves release notes from CHANGELOG.md and publishes them to GitHub._ + +### Updating release notes for already published versions + +Improvements to release notes can be done at anytime to any already published version: + +1. Update `CHANGELOG.md` with desired changes (ensure they'd also end in `master`) +2. Push updated release notes to GitHub by running: + `npx github-release-from-cc-changelog `