punkfuncgames/conventional-commits

Conventional Commits Reference

Spec: Conventional Commits 1.0.0 Enforced: ALL commits in this repository MUST follow this format.

Format

<type>(<scope>): <subject>

[optional body]

[optional footer(s)]

Rules

| Rule | Requirement | |------|-------------| | type | Required. Lowercase. One of the allowed types below. | | scope | Optional but encouraged. Lowercase kebab-case. Module or area affected. | | subject | Required. Imperative mood, lowercase start, no period, max 72 chars. | | body | Optional. Wrap at 100 chars. Explain what and why, not how. | | footer | Optional. BREAKING CHANGE: <desc> or Refs: #<issue>. | | breaking | Append ! after type/scope: feat(idle)!: remove legacy prestige API |

Allowed Types

| Type | When to Use | Example | |------|-------------|---------| | feat | New feature or capability | feat(wallet): add currency cap support | | fix | Bug fix (root cause, not workaround) | fix(bigdouble): correct infinity comparison operators | | test | Adding or updating tests only | test(wallet): add TryConsumeAll edge case coverage | | refactor | Code change that neither fixes a bug nor adds a feature | refactor(pool): extract spawn logic to dedicated method | | perf | Performance improvement | perf(idle): batch production calculations per frame | | docs | Documentation only (TESTING_GUIDE, ARCHITECTURE_GUIDE, etc.) | docs(core): add async test patterns section | | style | Formatting, whitespace, naming (no logic change) | style(core): apply consistent field naming convention | | build | Build system, CI/CD, assembly defs, packages | build(ci): add parallel test jobs to PR workflow | | chore | Maintenance tasks (gitignore, editor config, tool setup) | chore: add commitlint config | | revert | Revert a previous commit | revert: revert feat(wallet): add currency cap support |

Type Selection Guide

• Changed behavior? → feat (new) or fix (broken)
• Tests only? → test
• Moved code around, renamed, restructured? → refactor
• Faster but same behavior? → perf
• CI, asmdef, package.json, editor scripts? → build
• .gitignore, tool configs, skill files? → chore

Scopes (Module-Based)

Use the module name in lowercase kebab-case as scope:

| Scope | Module | |-------|--------| | core | Core/MVC, Composition, Extensions, Attributes | | idle | IdleModule (production, upgrade, prestige, boost, automation, offline, multiplier, time) | | wallet | WalletModule | | save | SaveModule | | ui | UIModule | | audio | AudioModule | | camera | CameraModule | | gamestate | GameStateModule | | input | InputModule | | scene | SceneModule | | asset | AssetModule | | localization | LocalizationModule | | steam | SteamModule | | pool | PoolModule | | stats | StatsModule | | undo | UndoModule | | floating-text | FloatingTextModule | | formula | FormulaModule | | log | LogModule | | bootstrap | Bootstrapping | | unlock | UnlockConditionModule | | bigdouble | Math/BigDouble | | ci | CI/CD, GitHub Actions | | editor | Editor scripts, inspectors |

Multiple scopes: If a commit spans multiple modules, use the primary module as scope. If truly cross-cutting, omit scope.

Subject Line Rules

1. Imperative mood — "add feature" not "added feature" or "adds feature"
2. Lowercase first letter — "add" not "Add"
3. No trailing period
4. Max 72 characters total (type + scope + subject)
5. What, not how — describe the change, not the implementation

Good vs Bad

# GOOD
feat(idle): add offline progress calculation
fix(wallet): prevent negative currency on concurrent consume
test(pool): add spawn/despawn lifecycle tests
refactor(core): extract disposable tracking to base class
build(ci): split test jobs for parallel execution

# BAD
feat(idle): Added offline progress calculation        # past tense
fix(wallet): Fixes negative currency bug.             # capitalized, period, third person
Updated tests                                          # no type, past tense, vague
refactor: refactored some stuff                        # vague, past tense
WIP                                                    # not conventional, no type
Initial plan                                           # not conventional, no type

Breaking Changes

Two ways to indicate:

# Option 1: ! after type/scope
feat(idle)!: replace IProductionService with IProductionEngine

# Option 2: Footer
feat(idle): replace IProductionService with IProductionEngine

BREAKING CHANGE: IProductionService renamed to IProductionEngine.
All consumers must update their constructor injections.

Multi-Line Body

Use when the subject alone doesn't explain the why:

fix(bigdouble): correct infinity comparison operators

Comparison operators (<, >, <=, >=) returned incorrect results
when either operand was infinity. The mantissa-based comparison
path did not account for special float values.

Refs: #19

Co-Author Footer

When AI assists with code:

feat(wallet): add multi-currency transaction support

Co-Authored-By: Claude <[email protected]>

Merge Commits

Merge commits from GitHub PRs are exempt from this format (GitHub generates them). But PR titles SHOULD follow conventional commit format since they become the merge commit message when squash-merging.

Commit Scope — One Logical Change Per Commit

• Each commit should represent ONE logical change
• Don't mix unrelated changes (e.g., a bug fix + a new feature)
• Tests for a feature go in the SAME commit as the feature (not separate)
• Exception: Large refactors may be split into a preparatory refactor commit followed by a feat commit

Forbidden Commit Patterns

| Pattern | Why It's Forbidden | |---------|--------------------| | WIP | Not conventional, not descriptive | | Initial plan | Not conventional, no type | | fix stuff / update things | Too vague | | Merge branch 'x' into y (manual) | Use git merge --no-edit or let GitHub handle it | | Past tense subjects | Must be imperative | | Subjects starting with capital letter | Must be lowercase |