Document branching conventions and tile serving MVP

2026-05-14 10:28:09 -07:00
parent 28d6c9626e
commit 295a25b7cd
2 changed files with 76 additions and 6 deletions
@@ -0,0 +1,63 @@
+# Branching Conventions
+
+Agrarian uses a lightweight branch model until team size, release cadence, or
+storefront channels require a heavier workflow.
+
+## Current Model
+
+- `main` is the only long-lived development branch.
+- Do not create a long-lived `dev` branch yet.
+- Use short-lived task branches for risky, multi-commit, or parallel work.
+- Small Codex-only changes may land directly on `main` when the worktree is
+  clean, the change is scoped, and validation is run.
+
+## Branch Names
+
+Use lowercase words separated by hyphens:
+
+```text
+type/short-description
+```
+
+Allowed `type` values:
+
+- `feature/` for new gameplay, tools, systems, or content.
+- `fix/` for bugs.
+- `docs/` for documentation-only changes.
+- `ops/` for infrastructure, build, server, repo, or deployment work.
+- `test/` for test-only changes.
+- `asset/` for art/content-only changes.
+- `experiment/` for throwaway prototypes that are not expected to merge as-is.
+
+Examples:
+
+```text
+feature/water-source-interaction
+fix/inventory-replication
+docs/storage-policy
+ops/tile-serving-mvp
+asset/ground-zero-foliage-pass
+experiment/weather-provider-adapter
+```
+
+## Rules
+
+- Keep branches focused on one roadmap item or tightly related slice.
+- Prefer branches that can be merged within days, not weeks.
+- Rebase or merge from `main` before final validation if the branch has drifted.
+- Delete task branches after merge.
+- Do not use personal-name branches for project work.
+- Do not use vague names such as `updates`, `misc`, `stuff`, or `wip`.
+- Do not commit raw terrain source datasets, generated builds, DerivedDataCache,
+  or large archive/source-art drops on any branch.
+
+## Future Triggers For A Long-Lived Dev Branch
+
+Create a long-lived staging branch only when one of these becomes true:
+
+- Multiple developers are merging daily.
+- Storefront channels need separate internal, investor, alpha, and public build
+  tracks.
+- Release candidates need stabilization while feature work continues.
+- Automated CI checks become strict enough that `main` should only receive
+  reviewed, green changes.