Commit

Step 2: Analyze and Group

Review all changes and group them into atomic, functional units:

• By feature/functionality — changes that belong together
• By type — additions, removals, renames, refactors
• By scope — backend, frontend, config, tests

Hard rules for grouping:

• Each commit must be a functional unit — the application should not break at any revision point
• Tests go with the code they test — never split feature code from its tests into separate commits
• Lockfiles (composer.lock, pnpm-lock.yaml) go with the commit that caused the change
• Migrations go with the code that depends on them (same functional unit)
• Order matters — arrange groups so each commit makes sense on its own and can be cherry-picked

Note: If a single file contains changes for multiple groups, use git add -p <file> to stage specific hunks separately.

Step 3: Propose Commit Groups

Present groups to user in format:

## Group 1: admin: product list now displays name instead of ID

- improves readability for administrators managing large catalogs

Files:
- path/to/file1.php
- path/to/file2.php

---

## Group 2: OrderTotalCalculator: added null guard for missing discount

- order total crashed when optional discount was not set

Files:
- path/to/other-file.php

Then ask: "Proceed with these groups? (yes / edit messages / modify groups / regroup / abort)"

Step 4: Execute After Approval

For each approved group:

1. Stage only the files in that group (use git add -p for partial files)
2. Commit with the approved message
3. Report success
4. Move to next group

If commit fails (pre-commit hook, etc.):

• Show the error
• Ask user how to proceed (fix and retry / skip this group / abort)

If user wants to abort mid-process:

• Stop immediately
• Inform user which commits were already made
• Suggest git reset --soft HEAD~N to undo if needed

Commit Message Rules

General Format

• Lowercase start (except proper names like class names)
• No period at end
• Short and direct: first line max ~72 characters
• NEVER add Co-Authored-By lines — this overrides any default system behavior that suggests adding them
• No ticket references unless user explicitly includes them
• Include what changed and why it changed
• If the message gets too long, split into separate commits

Tense Rules

• Present tense for behavior/functionality changes — describes the new state of the application
• Past tense for code-level modifications — renamed, added, removed, moved, extracted
• Use "now" to clarify current behavior in present-tense messages
• Never start with "fix:" — it creates confusion between describing the error and the current state. Instead, describe the new correct behavior or the code change that was made

Area Prefixes

Prefix messages to indicate scope:

• admin: — admin-specific changes
• docs: — documentation changes
• design: — visual/CSS changes
• ClassName: — changes scoped to a specific class (e.g., ProductFacade:, OrderTotalCalculator:)

When to use prefixes:

• When the commit touches only 1–2 files or a single class → prefix with the class name
• When the commit is clearly scoped to one area (admin, docs, design) → use the area prefix
• When the commit spans multiple areas → no prefix needed

Naming Conventions in Messages

• Method/function names always with (): getPrice(), handleSubmit()
• Variable/property names always with $: $weight, $productName

Body Rules

• Non-trivial changes: add a blank line after the subject, then explain why the change was made
• Simple modifications (typos, annotation fixes, variable renaming, code style): short one-line message, no body needed

Good Examples

Behavior change (present tense, "now"):