Branches and workflow design - NexusTomorrow/server GitHub Wiki
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.
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.
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.
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"]
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.
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.
| Knob | Default | Sets |
|---|---|---|
| The train's day | not set yet | The day of the week main moves |
- 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 bothmainanddev; 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 inContent/is a lane of its own.
| 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 |
| 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 |
- None beyond the open decisions above.