Skip to content

Commit 0d331c7

Browse files
wmontwewmontwe
committed
docs: add a git commit guide
1 parent c82d33b commit 0d331c7

File tree

2 files changed

+107
-0
lines changed

2 files changed

+107
-0
lines changed

‎docs/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
- [Manual Release (historical)](ci/HISTORICAL_RELEASE.md)
1111
- [Translations](translations.md)
1212
- [Java to Kotlin Conversion Guide](contributing/java-to-kotlin-conversion-guide.md)
13+
- [Git Commit Guide](contributing/git-commit-guide.md)
1314
- [Architecture Decision Records](architecture/adr/README.md)
1415
- [Accepted]()
1516
- [0001 - Switch From Java to Kotlin](architecture/adr/0001-switch-from-java-to-kotlin.md)

‎docs/contributing/git-commit-guide.md

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# Git Commit Guide
2+
3+
Use [Conventional Commits](https://www.conventionalcommits.org/) to write consistent and meaningful commit messages.
4+
This makes your work easier to review, track, and maintain for everyone involved in the project.
5+
6+
## ✍️ Commit Message Format
7+
8+
```git
9+
<type>(<scope>): <description>
10+
11+
<body>
12+
13+
<footer(s)>
14+
```
15+
16+
Components:
17+
18+
- `<type>`: The [type of change](#-commit-types) being made (e.g., feat, fix, docs).
19+
- `<scope>` **(optional)**: The [scope](#optional-scope) indicates the area of the codebase affected by the change (e.g., auth, ui).
20+
- `<description>`: Short description of the change (50 characters or less)
21+
- `<body>` **(optional)**: Explain what changed and why, include context if helpful.
22+
- `<footer(s)>` **(optional)**: Include issue references, breaking changes, etc.
23+
24+
### Examples
25+
26+
Basic:
27+
28+
```git
29+
feat: add QR code scanner
30+
```
31+
32+
With scope:
33+
34+
```git
35+
feat(auth): add login functionality
36+
```
37+
38+
With body and issue reference:
39+
40+
```git
41+
fix(api): handle null response from login endpoint
42+
43+
Checks for missing tokens to prevent app crash during login.
44+
45+
Fixes #123
46+
```
47+
48+
### 🏷️ Commit Types
49+
50+
| Type | Use for... | Example |
51+
|------------|----------------------------------|-------------------------------------------|
52+
| `feat` | New features | `feat(camera): add zoom support` |
53+
| `fix` | Bug fixes | `fix(auth): handle empty username crash` |
54+
| `docs` | Documentation only | `docs(readme): update setup instructions` |
55+
| `style` | Code style (no logic changes) | `style: reformat settings screen` |
56+
| `refactor` | Code changes (no features/fixes) | `refactor(nav): simplify stack setup` |
57+
| `test` | Adding/editing tests | `test(api): add unit test for login` |
58+
| `chore` | Tooling, CI, dependencies | `chore(ci): update GitHub Actions config` |
59+
| `revert` | Reverting previous commits | `revert: remove feature flag` |
60+
61+
### 📍Optional Scope
62+
63+
The **scope** is optional but recommended for clarity, especially for large changes or or when multiple areas of the
64+
codebase are involved.
65+
66+
| Scope | Use for... | Example |
67+
|------------|----------------|------------------------------------------|
68+
| `auth` | Authentication | `feat(auth): add login functionality` |
69+
| `settings` | User settings | `feat(settings): add dark mode toggle` |
70+
| `build` | Build system | `fix(build): improve build performance` |
71+
| `ui` | UI/theme | `refactor(ui): split theme into modules` |
72+
| `deps` | Dependencies | `chore(deps): bump Kotlin to 2.0.0` |
73+
74+
## 🧠 Best Practices
75+
76+
### 1. One Commit, One Purpose
77+
78+
- ✅ Each commit should represent a single logical change or addition to the codebase.
79+
- ❌ Don’t mix unrelated changes together (e.g., fixing a bug and updating docs, or changing a style and )
80+
adding a feature).
81+
82+
### 2. Keep It Manageable
83+
84+
- ✅ Break up large changes into smaller, more manageable commits.
85+
- ✅ If a commit changes more than 200 lines of code, consider breaking it up.
86+
- ❌ Avoid massive, hard-to-review commits.
87+
88+
### 3. Keep It Working
89+
90+
- ✅ Each commit should leave the codebase in a buildable and testable state.
91+
- ❌ Never commit broken code or failing tests.
92+
93+
### 4. Think About Reviewers (and Future You)
94+
95+
- ✅ Write messages for your teammates and future self, assuming they have no context.
96+
- ✅ Explain non-obvious changes or decisions in the message body.
97+
- ✅ Consider the commit as a documentation tool.
98+
- ❌ Avoid jargon, acronyms, or vague messages like `update stuff`.
99+
100+
## Summary
101+
102+
- Use [Conventional Commits](#-conventional-commits) for consistency.
103+
- Keep commit messages short, structured, and focused.
104+
- Make each commit purposeful and self-contained.
105+
- Write commits that make collaboration and future development easier for everyone—including you.
106+

0 commit comments

Comments
 (0)