Commit Style Guide

Oct 20, 2021

Dec 20, 2023

4 minutes

commitguidelinesfoundation

This style guide is the collection of precise rulesets that makes reviewing the Git commit messages and project history easier for everyone.

This comprehensive guide defines the precise rulesets for writing Git commit messages in the N3N projects. Following the Conventional Commits format, this guide provides specifications, examples, and best practices to make reviewing and understanding commit messages easier.

Commit Messages

This message structure, inspired by Conventional Commits, ensures clarity and consistency. It includes a commit message header, body, and footer for metadata.

Message Structure

<type>(<scope>): <description> [optional issue tags]
<BLANK LINE>
<optional body>
<BLANK LINE>
<optional footer(s)>

Commit Message Header

• type: Defines the kind of commit (e.g., new, fix, doc, imp, upd, fmt, chk, ext).
• scope: Names the parent folder containing the file subjected to changes.
• summary: Briefly describes the changes in the commit. Present tense, non-capitalized, and no period at the end.
• issue tag: Refers to the issue number from the repository. Can include multiple numbers.

Commit Message Body

Use the imperative, present tense. Explain the motivation for the change and provide a comparison of the previous behavior with the new one.

Commit Message Footer

Contains information about breaking changes, deprecations, and references to related issues, Jira tickets, or PRs.

Commit Types

1. fix: Patches a bug.
2. new: Introduces a new feature.
3. BREAKING CHANGE: Indicates a breaking API change.
4. doc: Identifies changes in documentation.
5. fmt: Signifies formatting or styling changes.
6. upd: Refactors production code without adding new features.
7. imp: Improves performance and applies optimizations.
8. chk: Adds missing test checks or fixes existing unit tests.
9. ext: Identifies extra changes affecting helper scripts or external dependencies.
10. bld: Involves changes to CI system, configurations, files, and scripts.

Scope

The scope should be the name of the parent directory containing the file subject to changes. It defines the commit location.

Summary

Use the imperative, present tense. Non-capitalized and no period at the end. Describes the changes concisely.

Issue Tag

References the particular issue that the commit resolves.

Message Body

Use the imperative, present tense. Explain the motivation for the change and provide a comparison of the previous behavior with the new one.

Message Footer

Contains information about breaking changes and deprecations. Also references GitHub issues, Jira tickets, and other related PRs.

Specifications

Refer to the guide for detailed specifications and rules for writing commit messages.

This Commit Style Guide ensures a consistent and understandable version history, promoting effective collaboration within the development team.

Examples

These samples demonstrate how to structure commit messages, including type, scope, summary, and optional issue tags.

1. New Feature:

   new(user-auth): implement OAuth2 authentication
   

2. Bug Fix:

   fix(api): resolve null pointer exception in data processing
   

3. Breaking Change:

   upd(config)!: migrate to YAML for configuration files
   

4. Documentation Update:

   doc(readme): update installation instructions
   

5. Code Formatting:

   fmt(src): reformat code for consistency
   

6. Performance Improvement:

   imp(algorithm): optimize sorting algorithm for faster execution
   

7. Check Addition:

   chk(tests): add unit tests for user authentication
   

8. External Dependency Update:

   ext(dependencies): update third-party library to version 2.0.0
   

9. Build Configuration Change:

   bld(ci): configure GitHub Actions workflow for automated builds
   

Additional Guidelines

• Keep the subject line concise (around 50 characters).
• Use the imperative mood in the subject line (e.g., "fix" instead of "fixed").
• Separate the subject from the body with a blank line.
• Use the body to explain what changes were made and why.
• Reference issues or pull requests in the footer using "Closes #<issue-number>" or "Resolves #<issue-number>".

Adhering to this commit style guide ensures clarity, consistency, and better collaboration within the development team.