Professional Commit Guide
1. Golden Rule: Atomic Commits ⚛️
Each commit should represent a single, logical, complete change that works on its own. Avoid bundling unrelated changes into one commit.
Example:
Instead of a big commit:
feat: Add Brand, Category and Product features
Split into atomic commits:
feat(brand): Add Brand entity and repositoryfeat(category): Add Category entity with self-referencing relationshipfeat(product): Add Product entity with relations to Brand and Categoryfeat(product): Implement ProductService logictest(product): Add unit tests for ProductService
Benefits:
- Easier reviews: Small focused changes are quicker to review.
- Safer reverts: Revert only the commit that caused the problem.
- Clear history: Makes the project timeline understandable.
2. Good Commit Message Structure: Conventional Commits 📝
This convention helps generate changelogs automatically and keeps git history consistent.
Format:
<type>(<scope>): <subject>
a. type (Change kind):
feat— new featurefix— bug fixdocs— documentationstyle— formatting (whitespace, lint, no logic changes)refactor— code restructure, no new feature or bug fixtest— tests added/changedchore— maintenance tasks (e.g. update .gitignore, build config)build— build system changes (e.g. pom.xml)
b. scope (Optional):
Indicates affected module/area, e.g. (product), (user), (order), (security), (config).
c. subject:
- Use imperative present tense (“Add” not “Added” or “Adding”).
- Capitalize first letter.
- Keep it short (under ~50 characters).
- Don’t end with a period.
3. Suggested Workflow 🚀
-
Create a branch: Always start features/bugfixes on a separate branch. Name it clearly:
feature/add-brand-crudfix/login-authentication-bug
-
Work & commit often: After each atomic change,
git addandgit commit. Don’t wait until the end. -
Write standardized commit messages: Follow Conventional Commits.
-
Open a Pull Request (PR): Push branch and create PR for code review.
-
Merge to main: After approval, merge into
developormain.
4. Real-world Example (Laptech project)
Task: “Build CRUD for Brand”. A possible commit sequence:
feat(brand): Add Brand entity with JPA and Lombok setupfeat(brand): Create BrandRepository interfacefeat(brand): Add DTO records and MapStruct mapper for Brandfeat(brand): Implement BrandService with CRUD business logicfeat(brand): Create BrandController with REST endpointsdocs(brand): Add Swagger documentation for Brand APIstest(brand): Add unit tests for BrandServiceImpltest(brand): Add integration tests for BrandControllerrefactor(common): Move SlugGenerator to common util packagefix(brand): Correctly handle unique slug generation in BrandService