Any repository set up with the Solo bot webhook for CI and release builds can opt into using the automated changelog provided in this utility. The benefits of using the changelog include:
- Automatically producing the description for the github release page, and optionally the docs, with zero effort.
- Ensuring that every change is described in the release notes, with links to Github issues.
- Ensuring that the release notes are consistently formatted across releases and repos.
- Ensuring that the release versions are incremented correctly according to semantic versioning.
Add a top-level directory called "changelog" in the repo. This directory will ultimately contain a structure like the following:
changelog/
v0.1.0/
summary.md
foo.yaml
bar.yaml
v0.2.0/
foo2.yaml
v0.2.1/
foo3.yaml
Here, v0.1.0
, v0.2.0
, and v0.2.1
represent released or unreleased versions of the project. The bot will
check to make sure there is exactly one directory corresponding to an unreleased version
(greater than the latest release tag) and that at least one new changelog file has been added.
A changelog file contains a list of changelog entries, like this:
changelog:
- type: NEW_FEATURE
description: Gloo releases now automatically publish a changelog to the docs.
issueLink: https://github.com/solo-io/gloo/issues/465
- ...
- ...
Type must be one of NEW_FEATURE
, FIX
, BREAKING_CHANGE
, DEPENDENCY_BUMP
, HELM
, UPGRADE
, or NON_USER_FACING
.
Changelog entries that are not of type NON_USER_FACING
or DEPENDENCY_BUMP
must have a description and an issue link.
Those fields are optional for NON_USER_FACING
and DEPENDENCY_BUMP
changes.
DEPENDENCY_BUMP
changes have a few additional required fields: dependencyTag
, dependencyOwner
, and dependencyRepo
. For example,
this is a valid changelog file containing a dependency bump:
changelog:
- type: DEPENDENCY_BUMP
description: Bumped the version of go-utils to pick up the new changelog feature.
dependencyOwner: solo-io
dependencyRepo: go-utils
dependencyTag: v0.6.2
Changelog entries can set an optional boolean field called resolvesIssue
. This can be used by CI
systems to automatically close issues linked to the changelog. The default value for this field is true
.
The description field should be one or more complete sentences (starting with a capital letter, ending with a period). The issue link should point to a valid github URL. These conventions are currently not validated, but may be in a future version.
The name of the changelog filename does not matter. It is useful to pick a unique name for the PR,
to avoid potential merge conflicts. For instance, you may add this change in a file called
publish_changelogs.yaml
. As long as it is valid yaml in the correct tag directory, it will be
considered valid.
There are two special files that can be added to assist with changelog rendering. These are:
summary.md
and closing.md
. These files can be added or modified at any time, and should
contain valid markdown. When the changelog is rendered, the summary will be included at the
top, before the list of changes, and the closing notes will be included at the end.
When changelogs are enabled, PRs must include a valid changelog file or they will fail verification and cannot be merged.
The changelog file must be included in the correct directory according to semver. For example, if the
last released version was v0.2.5
, new PRs that don't create breaking changes should add changelog
files into v0.2.6
(they should create the directory if it does not yet exist). If the PR contains
a breaking change entry, it should create or rename the existing directory to v0.3.0
.
For projects that have already released v1.0.0
, breaking changes should increment the major version
instead (v2.0.0
). Non-breaking changes should increment the minor version (v1.1.0
).
There is one special case for incrementing versions: publishing a stable 1.0 API. This can be done
by setting the releaseStableApi
field to true.
changelog:
- ...
. ...
releaseStableApi: true
Changelogs will automatically be rendered into a markdown string, and the CI release bot will immediately update a release description to be the changelog when a release is published. No manually entered description should be used (it will get overwritten).
Changelogs for a tag are merged and rendered in the following order:
- Summary
- Dependency bumps
- Breaking changes
- Upgrade notes
- Helm changes
- New Features
- Fixes
- Closing
If the contents for a section are empty, it is omitted.
A breaking change, upgrade note, helm change, new feature, or fix are rendered in the following way: <description> (<issueLink>)
Non-user facing changes are omitted from the changelog. If there are no user-facing changes in a release, the rendered notes will just say:
This release contained no user-facing changes.
This changelog can be pushed automatically to the docs using the PushDocsCli.