Skip to content

docs: Add documentation for releases and commit style #5675

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 19, 2023
Merged

docs: Add documentation for releases and commit style #5675

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0099611
docs: Add documentation for releases and commit style
mafredri Jan 11, 2023
1d64aaf
docs: Rewrite release process due to recent changes
mafredri Jan 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions docs/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -199,3 +199,50 @@ 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 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`.

### Creating a release

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 (via workflow dispatch)

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

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/).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When I merge PRs, I make sure that the first line of commit message is aligned with the convention. Should I also pay attention to other lines? For instance:

commit d9436fab69203740a25c29f2d27146bb04bc14c3 (upstream/main, main)
Author: Marcin Tojek <mtojek@users.noreply.github.com>
Date:   Wed Jan 11 16:05:42 2023 +0100
    docs: API enterprise (#5625)
    * docs: audit, deploymentconfig, files, parameters
    * Swagger comments in workspacebuilds.go
    * structs in workspacebuilds.go
    * workspaceagents: instance identity
    * workspaceagents.go in progress
    * workspaceagents.go in progress
    * Agents
    * workspacebuilds.go
...

I know that this can really long.

Copy link
Member Author

@mafredri mafredri Jan 12, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great question. I haven’t given it much thought to what it should look like.

Personally I usually either remove the bullets entirely, rewrite it as proper paragraphs (max width 72) or only keep/rewrite certain relevant bullet points.

Using the type/prefix is not necessary for these IMO. But it’s also not a crime to use them 😄

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SGTM!


**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.
25 changes: 16 additions & 9 deletions scripts/release.sh
View file
Original file line number Diff line number Diff line change
@@ -7,7 +7,7 @@ cdroot

usage() {
cat <<EOH
Usage: ./release.sh [--dry-run] [--ref <ref>] [--major | --minor | --patch]
Usage: ./release.sh [--dry-run] [-h | --help] [--ref <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
}