Chore: add git-cliff release workflow

[scode2277]

What does this PR change?

Add automated release workflow (git-cliff)

What this does

Every merge into main now opens a release PR with a generated changelog. Merging that PR creates the tag and publishes the GitHub Release. Nothing is tagged or published without a human merging the release PR first.

Why not release-please

We started with release-please but hit a wall: it only reads Conventional Commits, and anything that isn't feat:/fix:/deps: is invisible to it. Our contributors write freeform PR titles, and we don't want to force a naming convention on them or rename titles by hand each month. We also don't squash the monthly develop to main merge into a single commit, so the tool would either see nothing or drop most of the history.

We also ran into a setup issues worth recording: the default token couldn't open PRs until the repo setting was enabled.

Why git-cliff

git-cliff reads commits, not just conventional ones, and groups changelog entries by PR label instead of commit prefix. Since we already label PRs consistently (content:add, content:update, enhancement, certifications, dependencies), the changelog organizes itself with zero contributor friction. Freeform titles still show up, grouped correctly, each linked back to its PR and author.

How it works

Two workflows:

• release-pr.yml (on push to main): computes the next v0.0.x version from the latest tag, runs git-cliff to build the changelog, and opens a release PR. It skips itself when the only new commits are release/merge commits, so merging a release PR doesn't trigger another one.
• release-publish.yml (when a release/* PR merges): reads the version, creates the tag, and publishes the GitHub Release with that version's changelog section as the notes.

Config lives in cliff.toml (grouping rules, section names, skip rules for merge/release commits and dependency PRs).
Notes

Versioning is v0.0.x auto-increment for now (beta). There's a manual override input on the workflow if we ever need to set a specific version + dependencies-labelled PRs are intentionally hidden from the changelog so it's not overloaded by them.

Before merging this we have to enable the workflows to open PRs in the settings (Settings → Actions → General → Workflow permissions → "Allow GitHub Actions to create and approve pull requests")

Type of change

• New content
• Edit to existing content
• Outline / structure change
• Typo or formatting fix
• Tooling / config

If applicable

• Editing existing content: tagged the current contributors from the attribution list
• Framework has a steward: asked them to review
• Outline change: updated vocs.config.ts with the dev: true parameter
• Want community feedback: shared this PR in our Discord

Stuck on anything? Just write it here and we're happy to help.

[frameworks-volunteer]

Model: z-ai/glm-5.2 Reasoning: medium Provider: openrouter

Security + QA review complete. Approving.

Security: Clean

• All actions pinned to commit SHAs
• Permissions scoped correctly ({} at workflow level, per-job grants only what's needed)
• persist-credentials: false on both checkouts
• Version override input validated with regex before use
• No secrets, tokens, or injection vectors

QA: One non-blocking issue

• The committed file is CHANGELOG.MD (uppercase extension) but every workflow reference uses CHANGELOG.md (lowercase). On the ubuntu-latest runner (case-sensitive FS), touch CHANGELOG.md creates a separate lowercase file, git-cliff writes to the lowercase one, and add-paths: CHANGELOG.md only commits the lowercase version. The uppercase CHANGELOG.MD will sit empty and unused in the repo. Rename to CHANGELOG.md to avoid confusion. Not blocking since the workflow still functions.

Minor note: checkout is pinned to v5.0.1 while the deleted release-please.yml used v6.0.3. Not an issue functionally, just flagging in case the downgrade was unintentional.

The two-workflow design (release-pr on push to main, release-publish on release PR merge) is well thought out. The if guard that skips release-pr when the commit message contains chore(release): correctly prevents infinite loops. The release-publish trigger conditions (merged + base=main + head starts with release/ + has release label) are properly guarded.

[cloudflare-workers-and-pages]

Deploying frameworks with    Cloudflare Pages

Latest commit:	e4f4f5e
Status:	✅  Deploy successful!
Preview URL:	https://aac418b1.frameworks-573.pages.dev
Branch Preview URL:	https://fix-release-configs.frameworks-573.pages.dev

View logs

[mattaereal]

@frameworks-volunteer, how would this work exactly? I just read everything but have my doubts. The releases should be done when we do the monthly upgrade from dev to main, for example, on pull 522. That's always in a single PR, which squashes commits. Will that work as expected? How do we decide when this is a major version, minor version, etc?

[frameworks-volunteer]

Model: z-ai/glm-5.2 Reasoning: medium Provider: openrouter

Good questions. Both issues are real concerns with the current design.

1. Squash merge vs git-cliff

The PR description says "we don't squash the monthly develop to main merge" but PR #552 was actually squash-merged. The merge commit 4c1983c0 has a single parent (f22886bb), and only one commit was added to main. This is the squash-merge pattern, not a regular merge commit.

This matters because git-cliff groups changelog entries by github.pr_labels (see cliff.toml commit_parsers). When the monthly merge is squashed into one commit, git-cliff sees only that single commit ("Chore: monthly .org update (#552)") and looks up PR #552's labels. All the individual content PRs that were merged into develop (with their own content:add, content:update, etc. labels) are invisible -- they were squashed away.

For git-cliff to work as designed, the monthly develop-to-main merge must be a regular merge commit (not squash). That preserves the individual commit history on main, and git-cliff can resolve each commit back to its original PR and fetch the correct labels. The cliff.toml already skips merge commits (^Merge pull request -> skip), so the merge commit itself won't appear in the changelog -- only the individual content commits will.

If the squash approach stays, the changelog will show a single entry per month with whatever labels the monthly update PR has, which defeats the purpose of the label-based grouping.

2. Major/minor versioning

Currently there is no automated major/minor detection. The workflow always does v0.0.x patch auto-increment (the Compute next version step just bumps the patch number from the latest tag). The only way to set a major or minor bump is the manual workflow_dispatch input with a version override like v0.1.0.

There is no convention defined for when to use major vs minor vs patch. For a docs/content site like this, options:

• Patch (v0.0.x): content updates, typo fixes, dependency bumps (current default)
• Minor (v0.x.0): new framework pages, new sections, sidebar restructuring
• Major (vx.0.0): breaking structural changes, site redesign, scope changes

This should be documented somewhere (e.g. in cliff.toml comments or a RELEASES.md) so whoever triggers the manual override knows the convention. Until then, every release will be v0.0.x.

Summary: the workflow will work as expected ONLY if the monthly merge stops using squash. If squash stays, the changelog loses all individual PR context. And versioning needs a documented convention for major/minor bumps -- right now it is patch-only with manual override.

[mattaereal]

We should agree on how to move on, when merging PRs then @scode2277

[scode2277]

Actually, apart from #552 and #486 that were squash merged, we usually synced main via normal merge commit, not squashing.

Having that in mind, this workflow doesn't change anything for us nor contributors. We squash and merge on develop and when we sync on main we select "Merge commit" from the merge methods and merge normally.
That will trigger the first workflow that opens the PR and updates the version starting from 0.0.1; then, as soon as we check it and merge, the second workflow releases the tag on repo.

Regarding the minor/major version update, it's totally up to us. When the workflow opens the PR with the next available version, we can manually change it and choose the best version for us based on minor/major updates. In addition to that, there is the possibility to trigger the run of the workflow manually and feed it the wanted version, so it opens the PR automatically with the version we want.

Any doubts on this flow? @mattaereal