107 lines
3.1 KiB
Markdown
107 lines
3.1 KiB
Markdown
# 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.
|