Skip to content

[beta] Migrate changelog management to hark - #2290

Draft
xavdid wants to merge 5 commits into
betafrom
hark-backfill-beta
Draft

[beta] Migrate changelog management to hark#2290
xavdid wants to merge 5 commits into
betafrom
hark-backfill-beta

Conversation

@xavdid

@xavdid xavdid commented Sep 11, 2026

Copy link
Copy Markdown
Member

Why?

This is the beta version of our hark migration. See the linked PR below this description for more info.

This PR differs from master because its .hark files only include information about the beta branch. As a result, its changelog drops all information about GA releases. We might re-add these in the future, but we'll have to figure out a good way to do it. In the meantime, we add a line to the non-GA changelogs that mention that these changes are a superset of the GA ones.

Past that, this branch went through the same backfill process as master- break up the CHANGELOG and generate a bunch of files from it.

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
      • I also did some manual cleanup of things that weren't user facing (merge PRs, mostly). I figured now was the easiest time
  • ran hark build to transition CHANGELOG.md into a generated file
    • because this branch only has beta versions, this dropped a bunch of info. this is intended.
  • 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

Configuration

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant