How a change gets released
Bundu releases from one branch, the default branch main. There is no staging branch in this repository, and the policy is that there should not be one. A change reaches a release in four steps: a pull request, the required checks, a merge queue, and a scheduled job that tags the new tip of main.
This page describes the flow as it runs for bundu-docs today.
The flow
Section titled “The flow” branch off main | v pull request into main title: Conventional Commits, e.g. "feat: add the release page" body: "Closes #12", "Refs #12", or "No issue: <reason>" | | required checks run on the pull request: | lint / actionlint, lint / markdownlint, lint / yamllint | vite-plus / fmt, check, test, build | release version check, dependency review, PR metadata, | repository standards, issue attached, no agent-local files | CodeQL and Semgrep report results (their rulesets are in | evaluate mode; All checks green still reads their results) | All checks green (waits for every other check) v auto-merge --> merge queue | the required checks run again on the queued group | then the group merges with a merge commit v main (new tip) --> Cloudflare Workers Builds deploys the site | | Auto release job, every 15 minutes v is the tip tagged? no --> pick the bump from the PR titles breaking (!) --> refused; a person releases it any feat --> minor otherwise --> patch tag vX.Y.Z on the tip; publish as the latest releaseStep by step
Section titled “Step by step”1. Open a pull request
Section titled “1. Open a pull request”Branch from main. The branch name is free; the convention is a prefix such as feat/, fix/ or docs/.
The pull request title is the release input. It must be a Conventional Commits title:
| Title starts with | Bump it causes |
|---|---|
feat: or feat(scope): |
minor |
fix:, docs:, chore:, ci: and others |
patch |
feat!:, fix!: or any type!: |
refused; a person releases it as a major |
The title is not a required check in this repository. A title that is not Conventional Commits is not blocked, and the release treats it as a patch.
The body must close or reference an issue, or say why not. Closes #12 and Refs #12 both count. No issue: <reason> is accepted for a change with no issue, and the reason is given after the colon.
2. Required checks
Section titled “2. Required checks”Every check listed in the organization rulesets and the enterprise rulesets must pass before the pull request can merge. The gate named All checks green passes only after every other check on the commit is green, so a failing CodeQL result, for example, blocks the merge even though CodeQL is not in the list of required status checks.
Checks are not fixed by the lint jobs. A developer fixes a failing check locally and pushes again.
3. Merge queue
Section titled “3. Merge queue”Enabling auto-merge adds the pull request to the merge queue, which merges it once its checks pass. The queue builds a group of entries on top of the latest main, runs the required checks on that group, and merges the group with a merge commit. An entry that fails is removed, and the rest of the group is rebuilt.
The merge method is set in the repository’s queue settings; see repository rules.
4. Tagging the new tip
Section titled “4. Tagging the new tip”Every 15 minutes the Auto release job runs the release script for each organization. For a repository that has no staging branch and no release workflow of its own, the script works like this:
- Read the tip of the default branch. If a
v*tag already points at it, there is nothing to do. - Find the highest existing
vX.Y.Ztag. - Read the titles of the pull requests merged since that tag, up to the 50 most recent commits. If any title is a breaking change, stop and report it for a person. If any title is a
feat, the bump is minor. Otherwise it is patch. - Tag the tip with the new version, and publish a GitHub release for the tag, marked as the latest release, with generated notes.
When no version tag exists yet, the first release is v0.1.0 for a minor and v0.0.1 for a patch.
Because the job runs every 15 minutes, several merges can land between two runs. They receive one tag, on the tip, and the bump is the highest that any of them calls for.
The job reads tags, not the version in package.json. This repository’s package.json says 0.1.0, while its tags are at v0.4.4. The tags are the release record.
Majors
Section titled “Majors”A breaking change is never tagged automatically. The release job reports it and stops.
The central reusable trunk workflow can release a major when a repository calls it and runs it with bump: major from the Actions tab. bundu-docs does not call that workflow, so there is no manual path for a major in this repository today. A breaking change on bundu-docs therefore needs a maintainer to add that caller, or to tag the release by hand, before it can ship.
The semver:major label is a different thing. On a pull request that writes a version into a file such as package.json, the release version check accepts a major version only when the pull request has the semver:major label. The label does not start a release on its own.
Tags are permanent
Section titled “Tags are permanent”Version tags match v[0-9]*.[0-9]*.[0-9]*. The enterprise tag ruleset blocks deleting, force-updating and moving them. A released version cannot be changed after it is published; a fix is a new version.
Current state of this repository
Section titled “Current state of this repository”mainis protected, merges go through the merge queue, and each merge is tagged by the release job.- The latest tag,
v0.4.4, was cut by thestaging-version.ymlworkflow while astagingbranch still existed. It is marked as a beta pre-release. The latest published release isv0.4.0. - No commit had landed on
mainafterv0.4.4when this page was written, so the trunk path has not yet tagged anything in this repository.
What is not in this flow
Section titled “What is not in this flow”- Deployment. The site is deployed by Cloudflare Workers Builds on each push to
main, as set out in the repository README. This page does not cover the build settings. - Runner pinning. Such as
ubuntu-24.04. It is set per repository.