Migrate changelog management to hark

[xavdid]

Why?

Historically, we've maintained our CHANGELOG.md semi-by-hand. Our release script automatically pulls in PRs made since the last release, but otherwise dumps everything into a big markdown file that the release captain edits manually while the release is running. There's no opportunity to holistically edit the notes ahead of time and PR authors don't always write with a changelog reader in mind. Plus, all PRs go into the changelog, so it was incumbent on the captain to determine which were actually user-facing.

So, we've built out a CLI tool to better manage this process: hark.

Its primary purpose is to combine a bunch of .plan.md files into a CHANGELOG.md. The changelog becomes a purely generated file- all information flows in from the changefiles. hark also comes with utilities for creating and validating those changefiles, so our data layer is consistent.

hark's secondary purpose is to maintain a version.json list which tracks the release date and pinned API version of every release. It also has a CLI command we'll use during a release to maintain that list.

Lastly, it vends a few GitHub actions to help enforce good changefile hygiene.

You can read more about everything it does in its readme

This PR migrates this repo from the manual changelog to a fully hark-managed system. There's no impact to the actual SDK. This only affects us as the developers.

Important

For reviewers: while there is some diff in the changelog, it's limited to new versions (which were missing before), small prose fixes, and minor bullet reordering within releases. The new changelog is intended to be a superset of the original's content, but doesn't aim to match it letter-for-letter.

Note

CI will fail on this PR while https://github.com/stripe/hark is still private. We'll flip that to public very soon (see https://go/j/RUN_CODE-15185)

Afterwards, this PR will still have a failing CI job because it includes breaking changefiles but no migration guide. I'll just merge through that, since this is a one-time import.

What?

• Adds the .hark directory, which holds all the information needed to generate a changelog:
  • a versions.json which lists every release, its release date, and the pinned API version (if present)
    • this was put together using both the original changelog and the git tags. In a few cases, there were releases that had one or the other, so there was a bit of guesswork done for very old versions
  • a bunch of .change.md files
    • these were generated from each top-level bullet in a release.
    • they pulled in the relevant metadata about the change and all of the prose content from the sub-bullets
  • a bunch of intro-<version>.md files
    • are the bits of text that go before the bulleted release items
• ran hark build to transition CHANGELOG.md into a generated file
• update the PR template
  • drop the ## Changelog
  • add a ## Configuration section
    • add a checkbox to opt out of needing a changelog. this is used for non-user-facing changes
• modified the CI jobs
  • add changelog.yml to enforce changelog related rules:
    • every PR must have a changefile
    • all changefiles must be valid
    • PRs with breaking changes must modify the migration guide
  • add an exception in zizmor for pinned actions from stripe/hark/*
• (Go & PHP) ensure .hark isn't shipped with the SDK itself

See Also

• hark's README for information about the tool
• (for employees) the original design doc
• (for employees) go/hark-backfills has all the code used to backfill this data

Configuration

• skip-changefile: This PR does not need a changefile. (requires CI re-run)