Document branching conventions and tile serving MVP

This commit is contained in:
2026-05-14 10:28:09 -07:00
parent 28d6c9626e
commit 295a25b7cd
2 changed files with 76 additions and 6 deletions
+13 -6
View File
@@ -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.
+63
View File
@@ -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.