Skip to content

Branching & Commits

Jump to bottom
Pedro Monteiro edited this page Nov 27, 2025 · 1 revision

Branching & Commits

To keep our sanity (and our git history) intact, we follow a strict set of rules for how we name branches and write commit messages. It might feel like extra work at first, but it makes tracking down bugs and generating changelogs easier later on.

The Golden Rule: Never Commit to develop or master

Direct commits to the develop or master branches are forbidden.

  • develop: This is our main integration branch. It contains the latest features that are ready for the next release. This branch reflects the code currently in beta (app stores)

  • master: This reflects the code currently in production (app stores).

All work must be done on a dedicated branch created from develop.

1. Branch Naming Strategy

We follow the Conventional Branching strategy. Your branch name should tell us exactly what kind of work is inside it before we even look at the code.

Format

<type>/<short-description>

Types

  • feat: A new feature (e.g., adding a new screen).

  • fix: A bug fix (e.g., fixing a crash on login).

  • docs: Documentation changes (e.g., updating this wiki).

  • style: Formatting, missing semi-colons, etc; no code change.

  • refactor: Refactoring production code (e.g., renaming a variable).

  • test: Adding missing tests, refactoring tests; no production code change.

  • chore: Updating build tasks, package manager configs, etc; no production code change.

Examples

  • ✅ feat/dark-mode
  • ✅ fix/calendar-crash
  • ✅ docs/update-readme
  • ❌ my-work (Too vague)
  • ❌ fix_login (Wrong separator, use /)

2. Commit Messages

We use Conventional Commits. This allows us to automatically generate changelogs and version numbers based on the commit history.

Format

<type>(<optional scope>): <description>

[optional body]

[optional footer(s)]

The Breakdown

  1. Type: Must be one of the types listed above (feat, fix, chore, etc.).

  2. Scope (Optional): The specific part of the codebase you touched (e.g., login, map, ui).

  3. Description: A short summary of the change. Use the imperative mood ("add" not "added", "fix" not "fixed").

  4. Body (Optional): A longer description of why you made the change.

  5. Footer (Optional): References to issues (e.g., Closes #123) or breaking changes.

Examples

  • A simple feature:
feat(calendar): add support for weekly view
  • A bug fix with a reference:
fix(auth): handle timeout error on slow networks

The app was crashing when the API took longer than 5s to respond.
Added a try-catch block to handle the TimeoutException.

Closes #42
  • A breaking change (Scary!):
feat(api): update to v2 endpoints

BREAKING CHANGE: The fetchSchedule function now requires a specialized token.

3. The Pre-Commit Hook (Your Best Friend)

We have a script that automatically formats your code whenever you try to commit. If you don't use this, the CI pipeline will likely fail because of formatting issues.

How to install it: Run this once from the root of the repository:

chmod +x pre-commit-hook.sh
./pre-commit-hook.sh

What it does:

  1. When you run git commit, the hook triggers.

  2. It runs dart format on your staged files.

  3. If it changes anything, it effectively "cleans up" your mess before saving the commit.

4. The Workflow in Action

Here is how a typical contribution cycle looks:

1. Update your local repo:

git checkout develop
git pull origin develop

2. Create a branch:

git checkout -b feat/new-login-screen

3. Do the work:

Write code, save files.

4. Stage and Commit:

git add .
git commit -m "feat(login): implement new UI design"

(The pre-commit hook runs here. If it modifies files, you might need to add them and commit again).

5. Push:

git push -u origin feat/new-login-screen

6. Create Pull Request:

Go to GitHub and open a PR targeting develop.

Clone this wiki locally