AgrarianGameArchive/Docs/CommitMessageConventions.md

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:

Verb object or outcome

Examples:

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:

Why:
- Short reason for the change.

Validation:
- Command, editor check, packaged build, or manual test performed.

Example:

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:

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.