Commit Guidelines

The Crimsonland project follows strict commit guidelines to maintain a clear, reviewable, and useful git history.

Commit Message Format

All commits must follow the Conventional Commits format:

<type>: <description>

[optional body]

[optional footer]

Types

New feature - A wholly new capability added to the codebase.

feat: add plasma rifle weapon
feat: implement replay checkpoint verification

Bug fix - Corrects incorrect behavior.

fix: correct RNG seed initialization
fix: resolve creature heading wrap at tau boundary

Refactoring - Code restructuring without behavior change.

refactor: simplify perk selection logic
refactor: extract weapon damage calculation to helper

Performance improvement - Makes code faster without changing behavior.

perf: optimize collision detection grid
perf: cache weapon table lookups

Test changes - Add or modify tests.

test: add deterministic replay verification tests
test: add regression test for creature heading wrap

Documentation - Documentation-only changes.

docs: document float parity policy
docs: add parity workflow guide

Maintenance - Build, dependencies, tooling.

chore: update pytest to 9.0.2
chore: add ast-grep rule for float normalization

Code style - Formatting, whitespace, imports (no behavior change).

style: fix import ordering
style: apply ruff auto-fixes

Description Guidelines

Use Imperative Mood

Write as if giving a command: “add”, “fix”, “refactor” (not “added”, “fixes”, “refactoring”).

✅ fix: correct weapon damage calculation
❌ fix: corrects weapon damage calculation
❌ fix: correcting weapon damage calculation

Start with Lowercase

Begin the description with a lowercase letter.

✅ feat: add new weapon system
❌ feat: Add new weapon system

No Period at End

Do not end with a period.

✅ fix: resolve collision detection bug
❌ fix: resolve collision detection bug.

Keep Under 72 Characters

The first line should be concise (ideally under 72 characters).

Commit Body (Optional)

For complex changes, add a body explaining why (not what):

fix: preserve native float32 spill point in creature movement

The original decompile shows an explicit f32 cast at the assignment
point. Moving the spill earlier causes divergence in quest_1_8 capture
at frame 7756.

Evidence: analysis/ghidra/raw/crimsonland.exe_decompiled.c:21767
Session: docs/frida/differential-sessions/session-19.md

When to Include a Body

Parity Fixes

Always include evidence and session references for parity-related changes.

Non-Obvious Changes

Explain surprising or counter-intuitive decisions.

Breaking Changes

Document what breaks and migration path (also use BREAKING CHANGE: footer).

Complex Refactors

Explain the refactoring strategy and why it’s safe.

Commit Size

Keep commits small and reviewable - one subsystem at a time.

Good Commit Sizes

✅ Single logical change:

fix: correct zombie spawn rate calculation

✅ Focused refactor:

refactor: extract weapon damage helpers to module

✅ Isolated feature:

feat: add checkpoint verification to replay system

Bad Commit Sizes

❌ Too large (multiple unrelated changes):

fix: various gameplay fixes
- Fix zombie spawn rate
- Update weapon damage
- Refactor perk system
- Add new tests

❌ Too small (incomplete change):

fix: update zombie
fix: update zombie again
fix: finish zombie update

Commit Atomicity

Each commit should:

Pass All Checks

Every commit should pass just check (tests, linting, type checking).

Be Self-Contained

Changes should be complete and not depend on future commits.

Be Revertable

Should be safe to revert without breaking the codebase.

Have Clear Intent

Purpose should be obvious from message and changes.

Pre-Commit Verification

Before committing, verify your changes:

# Run full verification
just check

# Or use pre-commit hook (automatic)
prek install -c prek.toml -t pre-commit -t pre-push

The pre-commit hook will automatically run:

ruff check (linting)
ty check (type checking)
lint-imports (import contracts)
sg scan (structural rules)

Pull Request Guidelines

When using gh CLI for pull requests:

PR Title Format

PR titles must follow the same conventional commit format:

feat: add replay checkpoint verification
fix: resolve creature heading wrap bug
refactor: simplify perk selection logic

Creating PRs

Use body files to avoid escaping issues:

# Write PR body to file
cat > pr_body.md <<EOF
## Summary
- Add checkpoint verification to replay system
- Compare replay output to sidecar files
- Add deterministic tests for verification

## Evidence
- Implements design from docs/frida/differential-playbook.md
- Tested with quest_1_8 capture

## Testing
- [x] All tests pass
- [x] Replay verification works end-to-end
- [x] Checkpoint comparison produces expected diffs
EOF

# Create PR
gh pr create --body-file pr_body.md

Updating PRs

# Update PR body
gh pr edit --body-file pr_body.md

Merging PRs

Use squash merge to maintain clean history:

gh pr merge --squash <pr-number>

Squash merging combines all commits into one, so the PR title becomes the commit message.

Git Hygiene

Keep Changes Small

Prefer multiple small PRs over one large PR: ✅ Good:

PR #123: refactor: extract weapon damage helpers
PR #124: feat: add plasma rifle weapon
PR #125: test: add weapon damage parity tests

❌ Bad:

PR #123: feat: complete weapon system overhaul (300 files changed)

Avoid Merge Commits

Use rebase or squash to keep history linear:

# Rebase on main before merging
git fetch origin
git rebase origin/main

# Or use squash merge (preferred for PRs)
gh pr merge --squash

Interactive Rebase for Cleanup

Before pushing, clean up commit history:

# Rebase last 3 commits
git rebase -i HEAD~3

# Options:
# - squash: combine commits
# - reword: change commit message
# - edit: modify commit

Never rebase commits that have been pushed to shared branches.

Commit Message Examples

Good Examples

Simple Fix

fix: correct zombie spawn rate calculation

Feature with Context

feat: add replay checkpoint verification

Implements deterministic checkpoint comparison for replay files.
Compares runtime state to checkpoint sidecar at frame boundaries.

Part of parity verification workflow from differential-playbook.md.

Parity Fix with Evidence

fix: preserve native f32 spill in creature heading calculation

The original decompile shows explicit float cast at assignment.
Moving spill earlier causes divergence at quest_1_8 frame 7756.

Evidence: analysis/ghidra/raw/crimsonland.exe_decompiled.c:21767
Session: docs/frida/differential-sessions/session-19.md
Verified: quest_1_8 capture now passes checkpoint verification

Breaking Change

refactor: migrate weapon system to typed schemas

BREAKING CHANGE: Weapon serialization format changed from dict to
msgspec Struct. Old save files will not load.

Migration: Run `uv run scripts/migrate_saves.py` to convert.

Bad Examples

Too Vague

❌ fix: bug fixes✅ fix: correct zombie spawn rate calculation

What, Not Why

❌ fix: change constant to 0.6000000238418579✅ fix: preserve native f32 constant in turn rate calculation

Multiple Unrelated Changes

❌ chore: various updates and fixes✅ Split into multiple focused commits

Wrong Type

❌ feat: fix zombie spawn bug (should be fix:)✅ fix: correct zombie spawn rate calculation

Commit Workflow

Recommended workflow:

Make Focused Changes

Work on one logical change at a time.

Verify Changes

just check

Stage Files

git add <files>

Commit with Conventional Message

git commit -m "fix: correct zombie spawn rate calculation"

Push to Branch

git push origin feature-branch

Create PR

gh pr create --body-file pr_body.md

Resources

Conventional Commits

conventionalcommits.org - Full specification

gh CLI

cli.github.com - GitHub CLI documentation

Next Steps

Development Workflow

Learn the full contribution workflow

Verification Process

Ensure commits pass all checks

Code Style

Follow project coding standards

Parity Workflow

Understand parity-first development

Getting Started

Development

Guidelines

Commit Message Format

Types

Description Guidelines

Commit Body (Optional)

When to Include a Body

Commit Size

Good Commit Sizes

Bad Commit Sizes

Commit Atomicity

Pass All Checks

Be Self-Contained

Be Revertable

Have Clear Intent

Pre-Commit Verification

Pull Request Guidelines

PR Title Format

Creating PRs

Updating PRs

Merging PRs

Git Hygiene

Keep Changes Small

Avoid Merge Commits

Interactive Rebase for Cleanup

Commit Message Examples

Good Examples

Bad Examples

Commit Workflow

Resources

Conventional Commits

gh CLI

Next Steps

Development Workflow

Verification Process

Code Style

Parity Workflow

Build docs developers (and LLMs) love

Getting Started

Development

Guidelines

Documentation Index

​Commit Message Format

​Types

​Description Guidelines

​Commit Body (Optional)

​When to Include a Body

​Commit Size

​Good Commit Sizes

​Bad Commit Sizes

​Commit Atomicity

Pass All Checks

Be Self-Contained

Be Revertable

Have Clear Intent

​Pre-Commit Verification

​Pull Request Guidelines

​PR Title Format

​Creating PRs

​Updating PRs

​Merging PRs

​Git Hygiene

​Keep Changes Small

​Avoid Merge Commits

​Interactive Rebase for Cleanup

​Commit Message Examples

​Good Examples

​Bad Examples

​Commit Workflow

​Resources

Conventional Commits

gh CLI

​Next Steps

Development Workflow

Verification Process

Code Style

Parity Workflow

Build docs developers (and LLMs) love

Commit Message Format

Types

Description Guidelines

Commit Body (Optional)

When to Include a Body

Commit Size

Good Commit Sizes

Bad Commit Sizes

Commit Atomicity

Pre-Commit Verification

Pull Request Guidelines

PR Title Format

Creating PRs

Updating PRs

Merging PRs

Git Hygiene

Keep Changes Small

Avoid Merge Commits

Interactive Rebase for Cleanup

Commit Message Examples

Good Examples

Bad Examples

Commit Workflow

Resources

Next Steps