From 65216f8a22824d2b7d7ac6fea924c964e406440f Mon Sep 17 00:00:00 2001 From: nathan Date: Thu, 14 May 2026 10:39:10 -0700 Subject: [PATCH] Document commit message conventions --- AGRARIAN_DEVELOPMENT_ROADMAP.md | 8 +-- Docs/CommitMessageConventions.md | 106 +++++++++++++++++++++++++++++++ 2 files changed, 110 insertions(+), 4 deletions(-) create mode 100644 Docs/CommitMessageConventions.md diff --git a/AGRARIAN_DEVELOPMENT_ROADMAP.md b/AGRARIAN_DEVELOPMENT_ROADMAP.md index 3dfc801..000fefe 100644 --- a/AGRARIAN_DEVELOPMENT_ROADMAP.md +++ b/AGRARIAN_DEVELOPMENT_ROADMAP.md @@ -171,7 +171,7 @@ Remaining version 0.01 cleanup before moving deeper into new gameplay: - [!] 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. - [x] Finish branch naming conventions. -- [~] Finish commit message conventions. +- [x] 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. @@ -197,7 +197,7 @@ Goal: Prepare the project so all future development is controlled, recoverable, - [!] 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. - [x] Define branch naming conventions. -- [~] Define commit message conventions. +- [x] Define commit message conventions. - [x] Define GitHub/LFS free-tier storage guardrails. - [ ] Define backup expectations for NAS and repo. - [x] Confirm this roadmap file is committed or otherwise backed up. @@ -1408,7 +1408,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. - [x] Finish branch naming conventions. -- [~] Finish commit message conventions. +- [x] 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. @@ -1428,4 +1428,4 @@ Earliest incomplete foundation items: Immediate next item: -- [~] Finish commit message conventions. +- [ ] Define backup expectations for NAS and repository. diff --git a/Docs/CommitMessageConventions.md b/Docs/CommitMessageConventions.md new file mode 100644 index 0000000..ebeef60 --- /dev/null +++ b/Docs/CommitMessageConventions.md @@ -0,0 +1,106 @@ +# Commit Message Conventions + +Agrarian uses concise, plain-English commit messages that describe the user or +project-visible change. The goal is a history that can be read quickly during +debugging, investor build preparation, release notes, and handoff work. + +## Format + +Use a short imperative subject line: + +```text +Verb object or outcome +``` + +Examples: + +```text +Add water source interaction +Fix inventory persistence after reload +Document repository storage policy +Update Ground Zero foliage placement +Prepare investor demo packaging notes +``` + +Keep the subject line specific enough to identify the change without opening +the diff. + +## Rules + +- Use present-tense imperative verbs such as `Add`, `Fix`, `Update`, + `Document`, `Remove`, `Rename`, `Prepare`, `Verify`, or `Refactor`. +- Keep the first line under 72 characters when reasonable. +- Capitalize the first word. +- Do not end the subject with a period. +- Prefer one commit per roadmap item or tight implementation slice. +- Mention the system or asset affected when it helps future searches. +- Add a body when the reason, tradeoff, validation, or operational impact is + not obvious from the subject. +- Do not include secrets, passwords, tokens, private keys, or credentials in + commit messages. + +## Recommended Body + +Use a body for changes that affect builds, operations, storage policy, +networking, tile delivery, save compatibility, or player-visible behavior. + +Useful body structure: + +```text +Why: +- Short reason for the change. + +Validation: +- Command, editor check, packaged build, or manual test performed. +``` + +Example: + +```text +Add Ground Zero tile manifest prototype + +Why: +- Proves the first server-delivered terrain package path before large-scale + tile generation exists. + +Validation: +- Ran tile manifest generator. +- Verified manifest references the Ground Zero tile package. +``` + +## Commit Types By Area + +Commit subjects do not require prefixes, but these verbs should be consistent: + +- `Add` for new gameplay, tools, docs, assets, or systems. +- `Fix` for behavior that was wrong or broken. +- `Update` for expected changes to existing behavior or content. +- `Document` for docs-only changes. +- `Prepare` for build, release, investor demo, or operational setup work. +- `Verify` for test-only or validation-only changes. +- `Remove` for intentional deletion. +- `Refactor` only when behavior should not change. + +## Avoid + +- Vague messages like `updates`, `misc`, `changes`, `work`, or `wip`. +- Personal notes that do not describe the project change. +- Combining unrelated roadmap items into one commit. +- Referencing local-only paths or temporary machine details unless the commit is + explicitly about development operations. +- Large binary/data commits that violate the repository storage policy. + +## Multi-Commit Tasks + +For larger tasks, keep each commit independently understandable. A good series +reads like a short story: + +```text +Add water source actor +Place Ground Zero freshwater source +Verify Ground Zero water placement +Document Ground Zero freshwater source +``` + +If a task needs cleanup before merge, squash or amend only when it improves +history and does not hide useful validation details.