Skip to content

Add a Git commit guide #8965

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 9, 2025
Merged

Add a Git commit guide #8965

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
106 changes: 106 additions & 0 deletions docs/contributing/git-commit-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
<type>(<scope>): <description>

<body>

<footer(s)>
```

Components:

- `<type>`: The [type of change](#-commit-types) being made (e.g., feat, fix, docs).
- `<scope>` **(optional)**: The [scope](#optional-scope) indicates the area of the codebase affected by the change (e.g., auth, ui).
- `<description>`: Short description of the change (50 characters or less)
- `<body>` **(optional)**: Explain what changed and why, include context if helpful.
- `<footer(s)>` **(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.

Loading