GitHub Commit Convention Guide

In modern software development, maintaining a well-structured and easily navigable commit history is crucial for project success. A standardized commit message format not only enhances codebase readability but also streamlines project progress tracking and team collaboration. This guide introduces the widely-adopted AngularJS commit convention, which has become the de facto standard for many open-source projects and development teams.

Understanding Commit Message Structure

A well-formatted commit message consists of three distinct sections, separated by blank lines:

1. Header: A concise, single-line summary that describes the type and scope of changes.
2. Body: A detailed explanation of the changes, including their purpose and impact.
3. Footer: Optional metadata such as issue references or breaking change notices.

Header Format: Type, Scope, and Subject

The header follows a strict format that enables quick understanding of the commit’s purpose:

<type>(<scope>): <subject>

• Type (Required): Categorizes the nature of the change. Choose from these predefined types:

  • feat: New feature implementation
  • fix: Bug resolution
  • perf: Performance optimization
  • refactor: Code restructuring without changing functionality
  • docs: Documentation updates
  • style: Code style changes (formatting, missing semicolons, etc.)
  • test: Test-related changes
  • build: Build system or dependency modifications
  • revert: Reverting previous commits
  • ci: Continuous Integration configuration changes
  • chore: Maintenance tasks
  • release: Release version updates
  • workflow: Workflow automation changes

• Scope (Optional): Specifies the affected module or component:

  • Examples: global, common, route, component, utils, build
  • Format: fix(parser), feat(auth), docs(api)

• Subject (Required): A clear, concise description:

  • Keep it under 50 characters
  • Use imperative mood (“add” not “added”)
  • Complete the sentence: “If applied, this commit will [subject]”

Body Guidelines

The body provides essential context for the changes:

• Explain the “why” behind the changes
• Compare with previous behavior
• Include relevant technical decisions
• Keep it focused and relevant
• Use proper paragraphs and formatting

Footer Usage

The footer serves two primary purposes:

• Breaking Changes:

  • Start with BREAKING CHANGE:
  • Include detailed description
  • Provide migration instructions
  • Optionally mark in header with ! (e.g., feat(api)!: implement new authentication)

• Issue References:

  • Use standard formats: Closes #123, Fixes #456
  • Link multiple issues: Fixes #123, #456, #789
  • Include related issues: Related to #234

Enhancing Visibility with Emojis

While maintaining the conventional commit structure, strategic use of emojis can improve commit message visibility:

• ✨ :sparkles: New features
• 🐛 :bug: Bug fixes
• 📚 :books: Documentation
• 💅 :lipstick: Code style
• ♻️ :recycle: Refactoring
• ⚡️ :zap: Performance
• 🚧 :construction: Work in progress
• 🚀 :rocket: Deployment
• 📝 :memo: Text updates
• 🚨 :rotating_light: Critical fixes

For a comprehensive emoji reference, visit: GitHub Commit Emoji Guide

Implementing Commit Conventions

To ensure consistent commit message formatting across your team:

1. Automated Validation:

   • Use Husky for pre-commit hooks
   • Implement commitlint for message validation
   • Set up CI checks for commit format

2. Team Guidelines:

   • Document conventions in your project README
   • Provide commit message templates
   • Regular code reviews focusing on commit quality

3. Best Practices:

   • Keep commits focused and atomic
   • Write clear, descriptive messages
   • Reference issues and pull requests
   • Review commit history regularly

Summary

Adopting these GitHub commit conventions will significantly enhance your team’s development workflow. The benefits include:

• Improved codebase maintainability
• Better collaboration and code review efficiency
• Automated changelog generation
• Clearer project history
• Enhanced debugging and issue tracking

By following these guidelines, your team can maintain a professional, consistent, and valuable commit history that serves as a reliable reference for your project’s evolution.