GitHub Commit Message Guidelines

Last updated on 

Below are some guidelines on github commit message formats. These standards will help make the changes in commits more legible for your team.

Structure

  • Format: [TYPE] Description (refs #issue)
  • Example: [FIX] Correct user authentication flow (closes #123)

Types

  • [NEW] - New features
  • [FIX] - Bug fixes
  • [ENH] - Performance improvements
  • [CHANGE] - Changes in existing functionality
  • [REFACTOR] - Code refactoring
  • [TEST] - Adding or updating tests
  • [DOCS] - Documentation changes

Key Guidelines

  1. Link Issues
    • Directly before an issue number, use the keywords: closes, fixes, resolves
      • Example: fixes #10, closes #22
    • This automatically closes the referenced issue
  2. Description Quality
    • Use descriptive phrases, not just "fixed x"
    • Start with a verb. Use present tense.
    • Keep under 50 characters for the first line
    • Be specific, but not verbose about what changed
  3. Body Format (for longer commits)
    1. If a commit needs to be longer, follow this format:
[TYPE] Short summary (refs #issue)

Detailed explanation of changes
- Point 1
- Point 2

Breaking changes (if any)

Examples of Good Commits

  • [NEW] Add OAuth2 authentication (closes #45)
  • [FIX] Prevent duplicate user registration (fixes #89)
  • [CHANGE] Update Python minimum version to 3.7 (refs #123)
  • [DOCS] Update API authentication guides

Bad Examples to Avoid

  • ❌ fixed bug
  • ❌ updates
  • ❌ WIP
  • ❌ Quick fix