-
Notifications
You must be signed in to change notification settings - Fork 4.4k
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.
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
Introducing go-changelog #8387
Introducing go-changelog #8387
Conversation
46d5fc5
to
86b6b38
Compare
@@ -0,0 +1,3 @@ | |||
```release-note:improvement |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is how you create an improvement
@@ -0,0 +1,3 @@ | |||
```release-note:feature |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is how you create a feature.
@@ -0,0 +1,3 @@ | |||
```release-note:bug |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is how you create a bug.
|
||
```release-note:bug | ||
auto_encrypt: Fixed several issues around retrieving the first TLS certificate where it would have the wrong CN and SANs. This was being masked by a second bug (also fixed) causing that certificate to immediately be discarded with a second certificate request being made afterwards. | ||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is how you create multiple entries for a single PR.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You have to look at the file to see the other entries.
@@ -0,0 +1,3 @@ | |||
```release-note:improvement | |||
version: The `version` CLI subcommand was altered to always show the git revision the binary was built from on the second line of output. Additionally the command gained a `-format` flag with the option now of outputting the version information in JSON form. **NOTE** This change has the potential to break any parsing done by users of the `version` commands output. In many cases nothing will need to be done but it is possible depending on how the output is parsed. | |||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Long description with markdown formatting.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This looks great! Is actually running changelog-gen
something that should happen manually or could it eventually be integrated into CI? Should there be an (optional?) CI check/notice for validating that a PR adds a changelog entry file?
@mikemorris I don't think we can have a required check for the changelog entry for every PR for a couple of reasons.
As for a check being optional, it would make many PRs including most community PRs appear to be merged when failing checks. @i0rek Does this mean that once this PR is merged we should start adding changelog entries in files? |
7d58c9e
to
ca7250f
Compare
@mikemorris I think that running changelog-gen could be done by CI when we are comfortable with that. In terms of enforcing an entry, I am not sure how to do that best. I think it might be easier if we don't do it because of the reasons @mkeeler mentioned. We could however render the entry if it exists - that would help with the creation - I typoed them many times myself and they ended up not being included. @mkeeler yes, as soon as this merges we can start with the files. I am starting to coordinate with the team thats doing the next releases because it would be on them to incorporate |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice! I think this is going to be great
Just to chime in here: for the other project that uses this, we use https://github.com/hashicorp/go-changelog/tree/a22ca465bf7706bf125eac0a4ec4f3f7aed2fa15/cmd/changelog-pr-body-check to ensure every PR either has a changelog or explicitly says there isn't a changelog. YMMV with community interaction stuff, just wanted to note that By requiring an explicit opt-out, we could identify things that didn't have a changelog entry on accident, which was helpful for making sure things didn't accidentally get left out. Our contribution process was different in meaningful ways, however, so take all this with a grain of salt and in the spirit of breadcrumbs from previous travellers. :) |
I like that idea for catching missing changelogs. Maybe we could use a github label ( |
We did that, but found that a none file was an easier workflow for us for reasons involving our contributing process. YMMV. :) |
Since we are already doing things with labels, I think we should try that! @alvin-huang Could we add a check that checks if a file was added in |
* add templates for changelog-gen * add entry files for currently unreleased PRs on master
* add templates for changelog-gen * add entry files for currently unreleased PRs on master
* add templates for changelog-gen * add entry files for currently unreleased PRs on master
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
38Dpj2d6wuLunwdvJQzg8D56j8qQyu7XJR
This PR introduces go-changelog for consul, with the goal to automatically generate our changelog in the future. This PR is more of an introduction though, it adds entries for the currently unreleased PRs and showcases how to generate the changelog for them.
There are two notable things:
changelog.tmpl
andnote.tmpl
When running
changelog-gen
, it looks like this:The output is pretty much identical to the one we currently have in our changelog. I added a couple of dots at the end and the link to the PR references
pulls
instead ofissues
, but they are pointing to the same things. Note how everything is sorted properly and the links at the end are generated for you.