• Mahmood Ali's avatar
    Adopt go-changelog in Nomad (#10825) · 18d359f7
    Mahmood Ali authored
    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](https://github.com/hashicorp/consul/pull/8387), [Vault](https://github.com/hashicorp/vault/pull/10363), [Waypoint](https://github.com/hashicorp/waypoint/pull/1179). [Consul](https://github.com/hashicorp/consul/pull/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.
    18d359f7