From 24fce56c5e0b1c6c6d6bc7f1b4a76696063097f2 Mon Sep 17 00:00:00 2001 From: Yisroel Baum Date: Mon, 25 May 2026 08:06:59 +0300 Subject: [PATCH] clarify commit granularity --- ai/shared.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/ai/shared.md b/ai/shared.md index c07271e..351c88b 100644 --- a/ai/shared.md +++ b/ai/shared.md @@ -16,7 +16,9 @@ guides (`backend-context.md`, `frontend-context.md`) extend these. 4. Implement the code to make the test pass 5. Run the test to confirm it passes 6. Commit the implementation -7. Repeat for each new behavior +7. Repeat this red/green commit cycle for each new behavior. Do not + batch multiple behaviors into one failing-test commit and one + implementation commit when they can be reviewed separately. ## Code style @@ -32,8 +34,8 @@ guides (`backend-context.md`, `frontend-context.md`) extend these. and fakes - if a helper accepts a value, every caller must supply it. - First, explore the codebase to understand existing patterns - look at similar files for reference before writing anything -- Never use em dashes (—) in code, comments, or docblocks - use hyphens (-) - instead +- Never use em dash characters in code, comments, or docblocks - use + hyphens (-) instead ## Git commit style @@ -51,9 +53,21 @@ guides (`backend-context.md`, `frontend-context.md`) extend these. ## Git commits - Tests should be committed first, before implementation +- Prefer small, reviewable commits. Commit each meaningful step as soon as + it is green and the pre-commit checklist passes. - One logical change per commit - a commit may span multiple files when they form a single logical unit (e.g. a use case with its request and exception, or a Vue SFC with its Pinia store and route entry) +- Split commits by behavior, public contract, migration, wiring, docs, or + mechanical formatting when those parts can be reviewed independently. +- A multi-file commit is okay only when the files form one inseparable + change. Do not use "one logical change" to justify batching adjacent work. +- Do not batch several behaviors into one "tests" commit and one + "implementation" commit. Repeat the red/green cycle per behavior. +- Do not bundle backend and frontend changes unless both are required for + the same user-facing behavior. +- Do not bundle cleanup, refactors, renames, or formatting with feature + behavior. - Keep commits focused: not one file per commit, not unrelated work batched - Make commits frequent - commit each meaningful logical step as you go - Commits are for reviewing and documenting the development of code @@ -83,6 +97,8 @@ mechanical, not aspirational - a "yes" to all is required. - [ ] On a feature branch (not master/main). - [ ] This commit is one logical change. If it spans unrelated changes, stop and split it. +- [ ] This commit has been split as far as it can be while staying + reviewable. If any part can land independently, split it. - [ ] Tests for new behavior were committed BEFORE this implementation (or this commit IS the failing-test commit).