This project is mirrored from https://gitee.com/mirrors/nomad.git. Pull mirroring failed .
Repository mirroring has been paused due to too many failed attempts. It can be resumed by a project maintainer.
  1. 06 Jul, 2021 1 commit
    • 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