# 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.