From 0099611b52cab993dd434a0628b970b2218dc121 Mon Sep 17 00:00:00 2001 From: Mathias Fredriksson Date: Wed, 11 Jan 2023 18:21:01 +0000 Subject: [PATCH 1/2] docs: Add documentation for releases and commit style --- docs/CONTRIBUTING.md | 48 ++++++++++++++++++++++++++++++++++++++++++++ scripts/release.sh | 25 ++++++++++++++--------- 2 files changed, 64 insertions(+), 9 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 2f8b2713b293a..9cb126ea4fff5 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -199,3 +199,51 @@ one or more reviewers making new comments every time, then waiting for an updated change before reviewing again. All contributors, including those from maintainers, are subject to the same review cycle; this process is not meant to be applied selectively or to discourage anyone from contributing. + +## Releases + +Coder releases are automated via GitHub Actions. Specifically, the +[`release.yaml`](../.github/workflows/release.yaml) workflow. They are created +based on the current [`main`](https://github.com/coder/coder/tree/main) branch. + +The release notes for a release are automatically generated from commit titles +and metadata from PRs that are merged into `main`. + +### Creating a release (script) + +The preferred way to create a release is to use [`./scripts/release.sh`](../scripts/release.sh). This script will show a preview of the release that _would_ be created and if you choose to continue, automatically run and watch the release workflow for you. + +See `./scripts/release.sh --help` for more information. + +### Creating a release (workflow dispatch) + +Alternatively, the workflow can be dispatched manually from [Actions: Release](https://github.com/coder/coder/actions/workflows/release.yaml). Simply press "Run workflow" and set your preferred inputs. + +### Commit messages + +Commit messages should follow the [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) specification. + +Allowed commit types (`feat`, `fix`, etc.) are listed in [conventional-commit-types](https://github.com/commitizen/conventional-commit-types/blob/c3a9be4c73e47f2e8197de775f41d981701407fb/index.json). Note that these types are also used to automatically sort and organize the release notes. + +A good commit message title uses the imperative, present tense and is ~50 +characters long (no more than 72). + +Examples: + +- Good: `feat(api): Add feature X` +- Bad: `feat(api): Added feature X` (past tense) + +A good rule of thumb for writing good commit messages is to recite: [If applied, this commit will ...](https://reflectoring.io/meaningful-commit-messages/). + +**Note:** We lint PR titles to ensure they follow the Conventional Commits specification, however, it's still possible to merge PRs on GitHub with a badly formatted title. Take care when merging single-commit PRs as GitHub may prefer to use the original commit title instead of the PR title. + +### Breaking changes + +Breaking changes can be triggered in two ways: + +- Add `!` to the commit message title, e.g. `feat(api)!: Remove deprecated endpoint /test` +- Add the [`release/breaking`](https://github.com/coder/coder/issues?q=sort%3Aupdated-desc+label%3Arelease%2Fbreaking) label to a PR that has, or will be, merged into `main`. + +### Security + +The [`security`](https://github.com/coder/coder/issues?q=sort%3Aupdated-desc+label%3Asecurity) label can be added to PRs that have, or will be, merged into `main`. Doing so will make sure the change stands out in the release notes. diff --git a/scripts/release.sh b/scripts/release.sh index d68c6780987b0..8a3f74ec20f0e 100755 --- a/scripts/release.sh +++ b/scripts/release.sh @@ -7,7 +7,7 @@ cdroot usage() { cat <] [--major | --minor | --patch] +Usage: ./release.sh [--dry-run] [-h | --help] [--ref ] [--major | --minor | --patch] This script should be called to create a new release. @@ -17,18 +17,25 @@ based on if the release contains breaking changes or not. If the release contains breaking changes, a new minor version will be created. Otherwise, a new patch version will be created. -Set --ref if you need to specify a specific commit that the new version will -be tagged at, otherwise the latest commit will be used. - -Set --minor to force a minor version bump, even when there are no breaking -changes. Likewise for --major. By default a patch version will be created. - -Set --dry-run to see what this script would do without making actual changes. - To mark a release as containing breaking changes, the commit title should either contain a known prefix with an exclamation mark ("feat!:", "feat(api)!:") or the PR that was merged can be tagged with the "release/breaking" label. + +GitHub labels that affect release notes: + +- release/breaking: Shown under BREAKING CHANGES, prevents patch release. +- security: Shown under SECURITY. + +Flags: + +Set --major or --minor to force a larger version bump, even when there are no +breaking changes. By default a patch version will be created, --patch is no-op. + +Set --ref if you need to specify a specific commit that the new version will +be tagged at, otherwise the latest commit will be used. + +Set --dry-run to see what this script would do without making actual changes. EOH } From 1d64aaf097626967aec008403b444a24b06f0413 Mon Sep 17 00:00:00 2001 From: Mathias Fredriksson Date: Tue, 17 Jan 2023 14:16:36 +0000 Subject: [PATCH 2/2] docs: Rewrite release process due to recent changes --- docs/CONTRIBUTING.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 9cb126ea4fff5..387b524ae9639 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -202,22 +202,21 @@ be applied selectively or to discourage anyone from contributing. ## Releases -Coder releases are automated via GitHub Actions. Specifically, the -[`release.yaml`](../.github/workflows/release.yaml) workflow. They are created -based on the current [`main`](https://github.com/coder/coder/tree/main) branch. +Coder releases are initiated via [`./scripts/release.sh`](../scripts/release.sh) and automated via GitHub Actions. Specifically, the [`release.yaml`](../.github/workflows/release.yaml) workflow. They are created based on the current [`main`](https://github.com/coder/coder/tree/main) branch. -The release notes for a release are automatically generated from commit titles -and metadata from PRs that are merged into `main`. +The release notes for a release are automatically generated from commit titles and metadata from PRs that are merged into `main`. -### Creating a release (script) +### Creating a release -The preferred way to create a release is to use [`./scripts/release.sh`](../scripts/release.sh). This script will show a preview of the release that _would_ be created and if you choose to continue, automatically run and watch the release workflow for you. +The creation of a release is initiated via [`./scripts/release.sh`](../scripts/release.sh). This script will show a preview of the release that will be created, and if you choose to continue, create and push the tag which will trigger the creation of the release via GitHub Actions. See `./scripts/release.sh --help` for more information. -### Creating a release (workflow dispatch) +### Creating a release (via workflow dispatch) -Alternatively, the workflow can be dispatched manually from [Actions: Release](https://github.com/coder/coder/actions/workflows/release.yaml). Simply press "Run workflow" and set your preferred inputs. +Typically the workflow dispatch is only used to test (dry-run) a release, meaning no actual release will take place. The workflow can be dispatched manually from [Actions: Release](https://github.com/coder/coder/actions/workflows/release.yaml). Simply press "Run workflow" and choose dry-run. + +If a release has failed after the tag has been created and pushed, it can be retried by again, pressing "Run workflow", changing "Use workflow from" from "Branch: main" to "Tag: vX.X.X" and not selecting dry-run. ### Commit messages