diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 4fb83c9a759..1be2df36440 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -10,6 +10,7 @@ - [Manual Release (historical)](ci/HISTORICAL_RELEASE.md) - [Translations](translations.md) - [Java to Kotlin Conversion Guide](contributing/java-to-kotlin-conversion-guide.md) +- [Git Commit Guide](contributing/git-commit-guide.md) - [Architecture Decision Records](architecture/adr/README.md) - [Accepted]() - [0001 - Switch From Java to Kotlin](architecture/adr/0001-switch-from-java-to-kotlin.md) diff --git a/docs/contributing/git-commit-guide.md b/docs/contributing/git-commit-guide.md new file mode 100644 index 00000000000..85dd3a69746 --- /dev/null +++ b/docs/contributing/git-commit-guide.md @@ -0,0 +1,106 @@ +# Git Commit Guide + +Use [Conventional Commits](https://www.conventionalcommits.org/) to write consistent and meaningful commit messages. +This makes your work easier to review, track, and maintain for everyone involved in the project. + +## ✍️ Commit Message Format + +```git +(): + + + + +``` + +Components: + +- ``: The [type of change](#-commit-types) being made (e.g., feat, fix, docs). +- `` **(optional)**: The [scope](#optional-scope) indicates the area of the codebase affected by the change (e.g., auth, ui). +- ``: Short description of the change (50 characters or less) +- `` **(optional)**: Explain what changed and why, include context if helpful. +- `` **(optional)**: Include issue references, breaking changes, etc. + +### Examples + +Basic: + +```git +feat: add QR code scanner +``` + +With scope: + +```git +feat(auth): add login functionality +``` + +With body and issue reference: + +```git +fix(api): handle null response from login endpoint + +Checks for missing tokens to prevent app crash during login. + +Fixes #123 +``` + +### 🏷️ Commit Types + +| Type | Use for... | Example | +|------------|----------------------------------|-------------------------------------------| +| `feat` | New features | `feat(camera): add zoom support` | +| `fix` | Bug fixes | `fix(auth): handle empty username crash` | +| `docs` | Documentation only | `docs(readme): update setup instructions` | +| `style` | Code style (no logic changes) | `style: reformat settings screen` | +| `refactor` | Code changes (no features/fixes) | `refactor(nav): simplify stack setup` | +| `test` | Adding/editing tests | `test(api): add unit test for login` | +| `chore` | Tooling, CI, dependencies | `chore(ci): update GitHub Actions config` | +| `revert` | Reverting previous commits | `revert: remove feature flag` | + +### 📍Optional Scope + +The **scope** is optional but recommended for clarity, especially for large changes or or when multiple areas of the +codebase are involved. + +| Scope | Use for... | Example | +|------------|----------------|------------------------------------------| +| `auth` | Authentication | `feat(auth): add login functionality` | +| `settings` | User settings | `feat(settings): add dark mode toggle` | +| `build` | Build system | `fix(build): improve build performance` | +| `ui` | UI/theme | `refactor(ui): split theme into modules` | +| `deps` | Dependencies | `chore(deps): bump Kotlin to 2.0.0` | + +## 🧠 Best Practices + +### 1. One Commit, One Purpose + +- ✅ Each commit should represent a single logical change or addition to the codebase. +- ❌ Don’t mix unrelated changes together (e.g., fixing a bug and updating docs, or changing a style and ) + adding a feature). + +### 2. Keep It Manageable + +- ✅ Break up large changes into smaller, more manageable commits. +- ✅ If a commit changes more than 200 lines of code, consider breaking it up. +- ❌ Avoid massive, hard-to-review commits. + +### 3. Keep It Working + +- ✅ Each commit should leave the codebase in a buildable and testable state. +- ❌ Never commit broken code or failing tests. + +### 4. Think About Reviewers (and Future You) + +- ✅ Write messages for your teammates and future self, assuming they have no context. +- ✅ Explain non-obvious changes or decisions in the message body. +- ✅ Consider the commit as a documentation tool. +- ❌ Avoid jargon, acronyms, or vague messages like `update stuff`. + +## Summary + +- Use [Conventional Commits](#-conventional-commits) for consistency. +- Keep commit messages short, structured, and focused. +- Make each commit purposeful and self-contained. +- Write commits that make collaboration and future development easier for everyone—including you. +