From 295a25b7cdf7b97b870bdbf571e97fc73db842ef Mon Sep 17 00:00:00 2001 From: nathan Date: Thu, 14 May 2026 10:28:09 -0700 Subject: [PATCH] Document branching conventions and tile serving MVP --- AGRARIAN_DEVELOPMENT_ROADMAP.md | 19 ++++++---- Docs/BranchingConventions.md | 63 +++++++++++++++++++++++++++++++++ 2 files changed, 76 insertions(+), 6 deletions(-) create mode 100644 Docs/BranchingConventions.md diff --git a/AGRARIAN_DEVELOPMENT_ROADMAP.md b/AGRARIAN_DEVELOPMENT_ROADMAP.md index 2b4d4cb..3dfc801 100644 --- a/AGRARIAN_DEVELOPMENT_ROADMAP.md +++ b/AGRARIAN_DEVELOPMENT_ROADMAP.md @@ -170,13 +170,15 @@ Remaining version 0.01 cleanup before moving deeper into new gameplay: - [ ] Decide whether to keep current Unreal template variants or remove unused starter variants. - [!] Create protected `main` branch. Blocked while the repo remains private on the current GitHub plan; GitHub API reports this requires GitHub Pro or making the repository public. - [x] Decide whether to create/use a long-lived `dev` branch. Decision: do not use one yet; use `main` plus short-lived task branches until team size or release channels require a staging branch. -- [~] Finish branch naming and commit message conventions. +- [x] Finish branch naming conventions. +- [~] Finish commit message conventions. - [x] Define GitHub/LFS free-tier storage guardrails. - [ ] Define backup expectations for NAS and repository. - [ ] Create repeatable dedicated server build instructions. - [~] Finish required plugin documentation. - [ ] Confirm the project opens cleanly from a fresh checkout, not just the current working share. - [ ] Organize `Content/Agrarian/` folders and move starter/prototype assets into clearly named locations. +- [ ] Launch near-term MVP map-tile serving cloud VM. - [ ] Define MVP day/night length, survival pressure target, success loop, failure conditions, and closed-test readiness criteria. # Phase 0 - Project Foundation And Guardrails @@ -194,7 +196,7 @@ Goal: Prepare the project so all future development is controlled, recoverable, - [x] Commit clean baseline project. - [!] Create protected `main` branch. Blocked while the repo remains private on the current GitHub plan; GitHub API reports this requires GitHub Pro or making the repository public. - [x] Create `dev` branch if we want staging before main. Decision: do not create a long-lived `dev` branch yet. -- [~] Define branch naming conventions. +- [x] Define branch naming conventions. - [~] Define commit message conventions. - [x] Define GitHub/LFS free-tier storage guardrails. - [ ] Define backup expectations for NAS and repo. @@ -330,6 +332,10 @@ redownloaded when a player returns to a region. - [ ] Define tile adjacency and stitching rules. - [ ] Define tile versioning rules so terrain can improve without corrupting player state. - [ ] Define server-side tile delivery protocol. +- [ ] Launch a near-term MVP tile-serving cloud server on Ubuntu or another Linux distro. +- [ ] Publish a tiny Ground Zero tile manifest and package from the tile server. +- [ ] Prove client/server tile lookup, download, local cache, and redownload flow with the Ground Zero tile and immediate-neighbor metadata. +- [ ] Add tile-serving server cost controls and shutdown/runbook notes so MVP testing stays free or near-free. - [ ] Define client local tile cache layout. - [ ] Define local cache retention policy for old or unused tiles. - [ ] Define local cache redownload/revalidation behavior. @@ -931,8 +937,8 @@ Goal: Expand from a small test world toward a huge, regionally diverse, persiste - [ ] Define river, lake, coastline, and wetland generation rules. - [ ] Define missing/low-quality source data fallback rules. - [ ] Add streaming tests. -- [ ] Add server-delivered tile streaming prototype. -- [ ] Add client local tile cache prototype. +- [~] Add server-delivered tile streaming prototype. Near-term MVP proof is tracked in Phase 0.7. +- [~] Add client local tile cache prototype. Near-term MVP proof is tracked in Phase 0.7. - [ ] Add stale tile scrubber prototype. - [ ] Add tile redownload and version update prototype. - [ ] Add biome boundaries. @@ -1401,7 +1407,7 @@ Earliest incomplete foundation items: - [!] Create protected `main` branch. Blocked while the repo remains private on the current GitHub plan; GitHub API reports this requires GitHub Pro or making the repository public. - [x] Decide whether to create/use a long-lived `dev` branch. Decision: no long-lived `dev` branch yet. -- [~] Finish branch naming conventions. +- [x] Finish branch naming conventions. - [~] Finish commit message conventions. - [x] Define GitHub/LFS free-tier storage guardrails. - [ ] Define backup expectations for NAS and repository. @@ -1413,6 +1419,7 @@ Earliest incomplete foundation items: - [ ] Create the multiplayer/networking design document. - [ ] Create the persistence design document. - [ ] Create the Earth-scale terrain/tile streaming design document. +- [ ] Launch near-term MVP map-tile serving cloud VM and prove Ground Zero tile lookup/download/cache flow. - [ ] Create economy and AGR design document. - [ ] Create art direction, UX/HUD direction, coding standards, Blueprint standards, and asset/folder naming standards. - [ ] Organize `Content/Agrarian/` root folder and move starter/prototype assets into clear prototype folders. @@ -1421,4 +1428,4 @@ Earliest incomplete foundation items: Immediate next item: -- [~] Finish branch naming conventions. +- [~] Finish commit message conventions. diff --git a/Docs/BranchingConventions.md b/Docs/BranchingConventions.md new file mode 100644 index 0000000..604b6c7 --- /dev/null +++ b/Docs/BranchingConventions.md @@ -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.