bookshelf

git-workflow_22-03-2025

4 min read

Git Workflow Overview

Branching Strategy

Branch Naming Convention

  1. Structure: <type>/<short-descriptive-name>
    • Use lowercase, dash-separated names
    • Keep names concise, but descriptive
    • Examples:
      • feature/user-authentication
      • bugfix/fix-navbar-bug
      • chore/update-dependencies

Branch Types

  • feature/: New features or functionality
  • bugfix/: Bug fixes
  • chore/: Non-feature work like refactoring or updating dependencies
  • docs/: Documentation changes
  • hotfix/: Urgent bug fixes for production
  • release/: Version branches
  • refactor/: Code changes that don’t add features or fix bugs but improve code quality
  • test/: Adding or correcting tests
  • style/: Formatting or whitespace changes that don’t affect functionality

Commit Message Convention

Structure

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit Types

  • build: Changes related to the build system or external dependencies
  • ci: CI configuration changes (e.g., Travis, CircleCI)
  • docs: Documentation-only changes
  • feat: A new feature
  • fix: A bug fix
  • perf: Performance improvements
  • refactor: Refactoring code that doesn’t fix a bug or add a feature
  • style: Changes that don’t affect the code’s functionality (e.g., formatting, whitespace)
  • test: Adding or fixing tests

Scope

The scope should be the feature or section of the codebase affected by the commit. It helps describe where the change occurs.

Description

  • Use imperative present tense: “add”, “fix”, “refactor” (not “added” or “adding”)
  • No capital letters at the start
  • No dot at the end

Commit Body (Optional)

The body should explain the motivation for the change and how it contrasts with the previous behavior.

The footer is used for:

  • Breaking Changes: Must start with BREAKING CHANGE:
  • Issue References: Link to issues the commit addresses, e.g., Closes #42.

Breaking Changes

Breaking changes should either:

  • Use ! after the type (e.g., feat!: new feature)
  • Or use BREAKING CHANGE: in the footer

Example Commit Messages

Simple commit (no body or footer)

docs: correct spelling of CHANGELOG

Commit with scope

feat(lang): add Polish language

feat: allow config object to extend others

BREAKING CHANGE: 'extends' key now used for extending other config files

Commit with ! to indicate a breaking change

feat!: send an email when a product is shipped

Commit with multi-paragraph body and footers

fix: prevent racing of requests

Introduce request id to track latest requests and dismiss responses from others.

Reviewed-by: Z
Refs: #123

GitHub Issues and Pull Requests

Issues

  • Purpose: Track bugs, enhancements, or tasks that need attention.
  • Types:
    • Bug: Report issues and bugs.
    • Feature: Request a new feature.
    • Chore: Tasks like cleanup or improvements.
  • Labels: Use labels for categorization, e.g., bug, enhancement, help wanted.
  • Linking to PRs: Use Closes #<issue-number> or Fixes #<issue-number> in commit messages or PR descriptions to automatically close issues when the PR is merged.

Pull Requests (PRs)

  • Opening a PR:
    • Create a PR from your feature branch into main (or develop if you use that).
    • Add a clear title and description, linking to related issues.
  • Review Process:
    • Even if you’re the only developer, reviewing your own PR can help spot errors and improve the quality of the code.
  • Merging:
    • Once the PR is reviewed (and self-reviewed), merge it.
    • Use Squash and Merge for a clean commit history.
  • Deleting Branches: After merging, delete the feature branch to keep things clean.

Git Workflow: Steps for Working on a Feature

  1. Create an Issue (Optional):

    • Document the task in an issue if it’s not already tracked.
    • Example: “Add dark mode toggle”.

  2. Create a Branch:

    • From the main branch (or develop if applicable): git checkout main
      git pull origin main
      git checkout -b feature/dark-mode-toggle

  3. Work on the Feature:

    • Make your changes and commit them with detailed messages.
    • Example commit:
      git commit -m "feat: add dark mode toggle button"

  4. Push Your Branch:

    • Push the branch to GitHub: git push origin feature/dark-mode-toggle

  5. Create a Pull Request:

    • Create a PR from your branch into main.
    • Reference the issue in the PR description, e.g., Closes #123.

  6. Review and Merge:

    • Review the code (self-review or team review).
    • Once approved, merge the PR using Squash and Merge for cleaner history.

  7. Cleanup:

    • Delete the feature branch after merging: git branch -d feature/dark-mode-toggle

Best Practices

  1. Write Clear Commit Messages: Follow the Conventional Commit Guidelines for clarity.
  2. Keep Branches Small: Break larger features into smaller, manageable chunks.
  3. Test Locally: Always test your changes before pushing to GitHub.
  4. Use Issues to Track Work: Even for solo projects, track tasks to keep everything organized.
  5. Merge with Squash: For cleaner history, squash commits into a single commit before merging.

Additional Resources