This repository has been archived by the owner on Jan 8, 2024. It is now read-only.
Introduce go-changelog to Waypoint #1179
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This commit adds some essential template files for working with `go-changelog`. It also includes a basic readme for how to generate the proper CHANGELOG entries so that they can be generated with the tool. Finally, it introduces a github workflow for checking when pull requests forget to include a changelog file, with the option of being ignored if the proper label is applied to the PR.
briancain
added
the
pr/no-changelog
|
Future TODO:
|
|
I like it. I think the only suggestion I'd have is adding a make tasks perhaps or something for generating the CHANGELOG, then we can at least manually run that for now. |
|
Ooo, a make task is a good idea! I'll give that a go |
krantzinator
approved these changes
Mar 12, 2021
briancain
added a commit
that referenced
this pull request
Mar 18, 2021
Backport of Introduce go-changelog to Waypoint #1179
notnoop
pushed a commit
to hashicorp/nomad
that referenced
this pull request
Jul 6, 2021
Adopts [`go-changelog`](https://github.com/hashicorp/go-changelog) for managing Nomad's changelog. `go-changelog` is becoming the HashiCorp defacto standard tool for managing changelog, e.g. [Consul](hashicorp/consul#8387), [Vault](hashicorp/vault#10363), [Waypoint](hashicorp/waypoint#1179). [Consul](hashicorp/consul#8387) seems to be the first product to adopt it, and its PR has the most context - though I've updated `.changelog/README.md` with the relevant info here. ## Changes to developers workflow When opening PRs, developers should add a changelog entry in `.changelog/<PR#>.txt`. Check [`.changelog/README.md`](https://github.com/hashicorp/nomad/blob/docs-adopt-gochangelog/.changelog/README.md#developer-guide). For the WIP release, entries can be amended even after the PR merged, and new files may be added post-hoc (e.g. during transition period, missed accidentally, community PRs, etc). ### Transitioning Pending PRs can start including the changelog entry files immediately. For 1.1.3/1.0.9 cycle, the release coordinator should create the entries for any PR that gets merged without a changelog entry file. They should also move any 1.1.3 entry in CHANGELOG.md to a changelog entry file, as this PR done for GH-10818. ## Changes to release process Before cutting a release, release coordinator should update the changelog by inserting the output of `make changelog` to CHANGELOG.md with appropriate headers. See [`.changelog/README.md`](https://github.com/hashicorp/nomad/blob/docs-adopt-gochangelog/.changelog/README.md#how-to-generate-changelog-entries-for-release) for more details. ## Details go-changelog is a basic templating engine for maintaining changelog in HashiCorp environment. It expects the changelog entries as files indexed by their PR number. The CLI generates the changelog section for a release by comparing two git references (e.g. `HEAD` and the latest release, e.g. `v1.1.2`), and still requires manual process for updating CHANGELOG.md and final formatting. The approach has many nice advantages: * Avoids changelog related merge conflicts: Each PR touches different file! * Copes with amendments and post-PR updates: Just add or update a changelog entry file using the original PR numbers. * Addresses the release backporting scenario: Cherry-picking PRs will cherry-pick the relevant changelog entry automatically! * Only relies on data available through `git` - no reliance on GitHub metadata or require GitHub credentials The approach has few downsides though: * CHANGELOG.md going stale during development and must be updated manually before cutting the release * Repository watchers can no longer glance at the CHANGELOG.md to see upcoming changes * We can periodically update the file, but `go-changelog` tool does not aid with that * `go-changelog` tool does not offer good error reporting. If an entry is has an invalid tag (e.g. uses `release-note:bugfix` instead of `release-note:bug`), the entry will be dropped silently * We should update go-changelog to warn against unexpected entry tags * TODO: Meanwhile, PR reviewers and release coordinators should watch out ## Potential follow ups We should follow up with CI checks to ensure PR changes include a warning. I've opted not to include that now. We still make many non-changelog-worth PRs for website/docs, for large features that get merged in multiple small PRs. I did not want to include a check that fails often. Also, we should follow up to have `go-changelog` emit better warnings on unexpected tag.
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This commit adds some essential template files for working with
go-changelog. It also includes a basic readme for how to generate theproper CHANGELOG entries so that they can be generated with the tool.
Finally, it introduces a github workflow for checking when pull requests
forget to include a changelog file, with the option of being ignored if
the proper label is applied to the PR.