Document commit message conventions

2026-05-14 10:39:10 -07:00
parent 295a25b7cd
commit 65216f8a22
2 changed files with 110 additions and 4 deletions
@@ -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.