Git Commit Best Practices for Our Repository

[kmesiab]

Git Commit Best Practices for Our Repository

Our repository adheres to a set of best practices for Git commits. These practices are designed to ensure a clean, readable, and manageable commit history, which is crucial for effective collaboration and project maintenance. The following guidelines are to be followed by all contributors:

Quick Tips:

1. Run make lint before committing to ensure your code is properly formatted.
2. Separate your title from your description
3. Keep commit messages under 50 characters
4. Start your branch with feat|bugfix|docs|style|refactor|perf|test
5. Squash your commits into logical units of work

1. Rebase, Never Merge Commits

• Why Rebase?: Rebasing keeps the project history linear and clean. It avoids merge commits that can clutter the history and make it difficult to understand the sequence of changes.
• How to Implement:
  • Before pushing your changes, rebase your branch onto the upstream branch (commonly main or master).
  • Use git pull --rebase instead of git pull to avoid unnecessary merge commits.
  • Resolve any conflicts that arise during rebasing immediately and continue the rebase.

2. Declarative Commit Message Tone

• Why Declarative Tone?: A declarative tone in commit messages provides clarity and consistency. It helps in understanding what the commit does without diving into the details.
• How to Implement:
  • Write commit messages in the present tense. For example, use "Add feature" instead of "Added feature".
  • Begin the message with a capital letter and do not end with a period.
  • Keep the message concise but descriptive. Aim for clarity and brevity.

3. Code Quality

Run make lint before committing to ensure your code is properly formatted.

Additional Guidelines:

3. Atomic Commits

• Make small, self-contained commits that represent a single change or a logically grouped set of changes. This practice makes it easier to review changes and pinpoint issues.

4. Meaningful Commit Messages

• Always write meaningful commit messages that clearly describe what the commit achieves. Avoid vague messages like "fix bug" or "update file".

5. Branch Naming Conventions

• Use descriptive and consistent naming for branches. Include the type of work (feature, bugfix, hotfix) and a brief descriptor, e.g., feature/login-authentication.

[kmesiab]

When committing changes that resolve a particular issue, include the issue number in the commit message. This practice facilitates tracing the resolution of the issue through the commit history by enabling efficient search (grep) for relevant commits.