Branches and workflow design

The design for how work moves through the repository: the branches it lives on, what each change records, and how often and on what evidence it reaches main. It replaces the bootstrap branch and the "merge when ready" cadence on Branches and workflow, which describes the repository as it is today and takes this design on once the switch is made. The switch waits for step 3's second stage to merge.

The idea

In short

Reviewed work merges into dev as often as it's ready, and every merge notes what it changed in the changelog. Once a week, main moves to the newest dev commit that clears a fixed bar, seen working with the real client among it. Releases are tags on main at each milestone.

Why

main moved only when it felt ready, and fell fifteen commits behind its working branch, whose name, bootstrap, said nothing about what it was for. A fixed weekly step gives main a pace anyone can predict and the in-game checks a regular home, and a named bar says what "ready" means.

How it fits together

flowchart TD
    W["A work branch"] -->|"reviewed merge, with its changelog lines"| DV["dev"]
    DV -->|"weekly train, past the bar"| MA["main"]
    MA -->|"each milestone"| TG["A release tag"]

Loading

This is Git Flow's pair of long-lived branches, dev beside main, without its release and hotfix branches: the weekly train does a release branch's job.

Decisions

Locked

Two long-lived branches.

Branch	Holds	Moves when
main	What's been seen working with the real client; releases are tagged here	Once a week, on the train, and only the maintainer moves it
dev	Reviewed work that passes CI, on its way to main; the default branch, so a pull request lands there	A reviewed piece of work merges into it, as often as one is ready

Neither is rewritten once pushed: a ruleset on each refuses force pushes and deletion.

A work branch is named for the kind of work, never for its parent. Every one is cut from dev, and Git can't hold a branch dev and a branch dev/<topic> at once. Names are lowercase, with hyphens between words, and a work branch is deleted once it's merged.

Prefix	For	Example
feature/	New behaviour, a stage or a system	feature/stage-2b
fix/	A bug fix	fix/handoff-fault
refactor/	Restructuring with no change in behaviour, reviewed for exactly that	refactor/owner-base
audit/	Checking one feature area's messages against the client	audit/chat
docs/	The repository's own docs: the README, CONTRIBUTING, the changelog	docs/contributing-branches
chore/	Tooling, CI and dependencies	chore/settings-generator
ci/	A throwaway copy pushed for a test run, deleted after it	ci/world-scenarios

Every merge into dev notes what it changed in CHANGELOG.md, under Unreleased, grouped as Added, Changed and Fixed, in words a player or an operator would use. The format is Keep a Changelog.

Once a week, the train moves main to the newest dev commit that clears the bar, and the changelog's Unreleased section takes that day's date as its heading. A commit that misses the bar waits for the next week, and if nothing new clears it, main stays where it is. When a play session finds a problem, main takes the last commit before it that clears the bar.

#	The bar	Shown by
1	Every test application passes, none skipped, on the exact commit	A CI run whose tree matches the commit
2	Every piece of work in it was reviewed, its findings fixed or ruled on	The review of each merge
3	It's been seen working with the real client	The in-game checks it owes, cleared in that week's play session
4	It upgrades cleanly	When a schema changed, migrate run over a database the previous main made
5	It's documented	This wiki matches the commit, the README.md is current, and the changelog has a line for every change

A release is a tag on main at each milestone, versioned by date (2026.10.25), with the changelog's sections since the last release as its notes. A server deploys only tagged releases.

Knobs

Knob	Default	Sets
The train's day	not set yet	The day of the week main moves

Open

• The train's day.
• A fix for a released server would take the standard route, a hotfix/ branch from the release's tag merged into both main and dev; it's added to the rules when a server first needs one.
• Content work gets a content/ prefix once the content pipeline exists, since authoring a zone's data in Content/ is a lane of its own.

Rejected

Idea	What killed it
main as the trunk, with a separate stable branch for what's proven	It changes what main means and who may move it. Keeping main as the proven line keeps both
Sub-branches named after their parent, dev/<topic>	Git can't hold a branch dev and a branch dev/<topic> at once, and the parent is always dev anyway
Git Flow's release/ branches	The weekly train and its bar already do what a release branch is for
Moving main whenever it feels ready	main fell fifteen commits behind, and nothing said what ready meant

Verification status

Claim	Basis
A branch and a branch under its name can't coexist	How Git stores branch names, as paths
Renaming a branch on GitHub keeps links and pull requests working	GitHub's rename redirects them

Open questions

• None beyond the open decisions above.