From bbe7335d2cd5e16be84d25447be0a3dffee7913e Mon Sep 17 00:00:00 2001 From: Ewan Harris Date: Thu, 10 Sep 2026 22:29:28 +0100 Subject: [PATCH 1/4] chore: add release infrastructure and changelog documentation Adds the CHANGELOG.md seed file, RELEASING.md maintainer guide, and a PR template that prompts contributors to provide user-facing changelog overrides via release-please's BEGIN_COMMIT_OVERRIDE mechanism. CONTRIBUTING.md is updated to note that conventional commit prefixes feed the changelog automatically, with a pointer to RELEASING.md for the override workflow. --- .github/PULL_REQUEST_TEMPLATE.md | 18 ++++++++++ CHANGELOG.md | 1 + CONTRIBUTING.md | 2 ++ RELEASING.md | 62 ++++++++++++++++++++++++++++++++ 4 files changed, 83 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CHANGELOG.md create mode 100644 RELEASING.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..9f28879 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,18 @@ +## Description + + + +## Changelog + + diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..825c32f --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1 @@ +# Changelog diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b9e30fc..7baf346 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,6 +54,8 @@ The user-facing language specification lives in [`docs/language-spec.md`](./docs Please make sure to follow the existing code style and include tests for your changes. Pull request titles must follow the [Conventional Commits](https://www.conventionalcommits.org/) format, as it is validated in CI. +Commit message prefixes feed the changelog automatically on release. For user-facing changes where the commit message is too terse, add a `BEGIN_COMMIT_OVERRIDE` block to the PR body — see [RELEASING.md](./RELEASING.md#overriding-a-changelog-entry) for details. + ## Getting in Touch ### Have a question or problem? diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000..0bf4807 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,62 @@ +# Releasing + +Releases are managed by [release-please](https://github.com/googleapis/release-please). The process is automated — maintainers only need to merge a release PR and confirm a few things beforehand. + +## How it works + +1. Every merge to `main` that includes a conventional commit prefix (`feat:`, `fix:`, `perf:`, etc.) causes release-please to open or update a release PR titled `release: vX.Y.Z`. +2. The release PR contains an updated `CHANGELOG.md` and a bumped version in `.release-please-manifest.json`. +3. Merging the release PR tags the commit, which triggers CI to verify the tag matches the manifest and to undraft the GitHub Release. + +### Version bump rules + +| Commit prefix | Bump | +|---|---| +| `feat:` | minor (patch if pre-1.0) | +| `fix:`, `perf:`, `refactor:` | patch | +| `feat!:` or `BREAKING CHANGE:` footer | major | + +## Cutting a release + +1. Review the open release-please PR — confirm the version and changelog look right. +2. Approve and merge the PR. +3. CI will tag the commit, verify versions match, and publish the GitHub Release automatically. + +You can also trigger a release manually via **Actions → release-please → Run workflow**, choosing the bump type or supplying an explicit version. + +## Changelog entries + +release-please builds the changelog from commit messages since the last tag using the sections defined in `release-please-config.json`: + +| Prefix | Section | Visible | +|---|---|---| +| `feat:` | Added | yes | +| `fix:` | Fixed | yes | +| `perf:`, `refactor:` | Changed | yes | +| `revert:` | Removed | yes | +| `docs:` | Documentation | yes | +| `test:`, `ci:`, `chore:` | Miscellaneous | hidden | + +### Overriding a changelog entry + +When a commit message is too terse or developer-focused, you can override the changelog entry from the PR body. Add this block anywhere in the PR description: + +``` +BEGIN_COMMIT_OVERRIDE +feat: describe the change in user-facing terms +END_COMMIT_OVERRIDE +``` + +release-please uses this text instead of the commit message when building the changelog. + +### Breaking changes + +Add a `BREAKING CHANGE:` footer to the commit body (not the subject line): + +``` +feat!: remove the Foo option + +BREAKING CHANGE: the Foo option has been removed. Use Bar instead. +``` + +This produces a major version bump and a dedicated breaking changes section in the changelog. From 1d3f02604cbf248de6566f3b56b161268ef1abfb Mon Sep 17 00:00:00 2001 From: Ewan Harris Date: Fri, 11 Sep 2026 15:57:08 +0100 Subject: [PATCH 2/4] chore: align PR template with openfga org template --- .github/PULL_REQUEST_TEMPLATE.md | 40 +++++++++++++++++++++++++++----- 1 file changed, 34 insertions(+), 6 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 9f28879..8641b66 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,18 +1,46 @@ + + + + ## Description + +#### What problem is being solved? - +#### How is it being solved? -## Changelog +#### What changes are made to solve it? +## Changelog -Leave this section blank if the commit message is sufficient (most bug fixes and chores). +## References + + +## Review Checklist +- [ ] I have clicked on ["allow edits by maintainers"](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). +- [ ] I have added documentation for new/changed functionality in this PR or in a PR to [openfga.dev](https://github.com/openfga/openfga.dev) [Provide a link to any relevant PRs in the references section above] +- [ ] The correct base branch is being used, if not `main` +- [ ] I have added tests to validate that the change in functionality is working as expected From 4c92197fee3dedc72a3e1643f0f5b22523ed7705 Mon Sep 17 00:00:00 2001 From: Ewan Harris Date: Wed, 16 Sep 2026 14:11:23 +0100 Subject: [PATCH 3/4] chore: make release workflow manual-only --- .github/workflows/release-please.yml | 5 ----- RELEASING.md | 13 ++++++------- 2 files changed, 6 insertions(+), 12 deletions(-) diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml index 4913b05..0dbb604 100644 --- a/.github/workflows/release-please.yml +++ b/.github/workflows/release-please.yml @@ -4,8 +4,6 @@ permissions: contents: read on: - push: - branches: [main] workflow_dispatch: inputs: bump-type: @@ -33,9 +31,6 @@ jobs: permissions: contents: write pull-requests: write - if: | - github.event_name == 'workflow_dispatch' || - startsWith(github.event.head_commit.message, 'release:') uses: openfga/.github/.github/workflows/release-please.yml@835baf31562809ad9eb884c73efc5b79318f700f # pin@main with: trigger-event: ${{ github.event_name }} diff --git a/RELEASING.md b/RELEASING.md index 0bf4807..436c1a8 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -4,8 +4,8 @@ Releases are managed by [release-please](https://github.com/googleapis/release-p ## How it works -1. Every merge to `main` that includes a conventional commit prefix (`feat:`, `fix:`, `perf:`, etc.) causes release-please to open or update a release PR titled `release: vX.Y.Z`. -2. The release PR contains an updated `CHANGELOG.md` and a bumped version in `.release-please-manifest.json`. +1. A maintainer triggers the release workflow manually via **Actions → release-please → Run workflow**. +2. release-please opens or updates a release PR titled `release: vX.Y.Z`, containing an updated `CHANGELOG.md` and a bumped version in `.release-please-manifest.json`. 3. Merging the release PR tags the commit, which triggers CI to verify the tag matches the manifest and to undraft the GitHub Release. ### Version bump rules @@ -18,11 +18,10 @@ Releases are managed by [release-please](https://github.com/googleapis/release-p ## Cutting a release -1. Review the open release-please PR — confirm the version and changelog look right. -2. Approve and merge the PR. -3. CI will tag the commit, verify versions match, and publish the GitHub Release automatically. - -You can also trigger a release manually via **Actions → release-please → Run workflow**, choosing the bump type or supplying an explicit version. +1. Go to **Actions → release-please → Run workflow** and choose the bump type (or supply an explicit version). +2. release-please opens a PR titled `release: vX.Y.Z` — review the version and changelog. +3. Approve and merge the PR. +4. CI will tag the commit, verify versions match, and publish the GitHub Release automatically. ## Changelog entries From 7055d69c56f23020ee18d566148068051f12da76 Mon Sep 17 00:00:00 2001 From: Ewan Harris Date: Wed, 16 Sep 2026 14:50:55 +0100 Subject: [PATCH 4/4] chore: address Copilot review feedback --- .github/PULL_REQUEST_TEMPLATE.md | 10 +++------- .github/workflows/release-please.yml | 5 +++++ RELEASING.md | 14 ++++++++------ 3 files changed, 16 insertions(+), 13 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 8641b66..a8562c1 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -18,13 +18,9 @@ If your PR is under active development, please submit it as a "draft". Once it's ## Changelog diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml index 0dbb604..4913b05 100644 --- a/.github/workflows/release-please.yml +++ b/.github/workflows/release-please.yml @@ -4,6 +4,8 @@ permissions: contents: read on: + push: + branches: [main] workflow_dispatch: inputs: bump-type: @@ -31,6 +33,9 @@ jobs: permissions: contents: write pull-requests: write + if: | + github.event_name == 'workflow_dispatch' || + startsWith(github.event.head_commit.message, 'release:') uses: openfga/.github/.github/workflows/release-please.yml@835baf31562809ad9eb884c73efc5b79318f700f # pin@main with: trigger-event: ${{ github.event_name }} diff --git a/RELEASING.md b/RELEASING.md index 436c1a8..9933db7 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -10,11 +10,13 @@ Releases are managed by [release-please](https://github.com/googleapis/release-p ### Version bump rules -| Commit prefix | Bump | -|---|---| -| `feat:` | minor (patch if pre-1.0) | -| `fix:`, `perf:`, `refactor:` | patch | -| `feat!:` or `BREAKING CHANGE:` footer | major | +The repo uses `bump-minor-pre-major` and `bump-patch-for-minor-pre-major`, so bumps differ before and after v1.0.0: + +| Commit | Before v1.0.0 | v1.0.0 and later | +|---|---|---| +| `feat:` | patch | minor | +| `fix:`, `perf:`, `refactor:` | patch | patch | +| Any `type!:` or `BREAKING CHANGE:` footer | minor | major | ## Cutting a release @@ -58,4 +60,4 @@ feat!: remove the Foo option BREAKING CHANGE: the Foo option has been removed. Use Bar instead. ``` -This produces a major version bump and a dedicated breaking changes section in the changelog. +This produces a dedicated breaking changes section in the changelog and a major version bump (minor bump before v1.0.0).