AgrarianGameArchive/Docs/BranchingConventions.md

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 protection/review expectations are defined in Docs/Ops/GitHubBranchProtectionAndReviewRules.md.

Branch Names

Use lowercase words separated by hyphens:

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:

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.

Protection Enforcement

The repository is currently private and staying on the free tier. GitHub does not currently allow branch protection/ruleset enforcement for this private repo without upgrading or making it public, so version 0.01 uses documented process rules and a pull request template. Enforced protected main remains tracked in the later build/release pipeline milestone.