Skip to content

Instantly share code, notes, and snippets.

@abmmhasan

abmmhasan/Commit Message Guideline.md

Last active November 26, 2024 08:22
Show Gist options
  • Save abmmhasan/95fdb09f62fe0adc4ee148040376967e to your computer and use it in GitHub Desktop.
Save abmmhasan/95fdb09f62fe0adc4ee148040376967e to your computer and use it in GitHub Desktop.
Download ZIP
VCS Commit Message Structure
Raw
Commit Message Guideline.md

Commit Message Guidelines

Adopt a structured approach to commit messages using the Conventional Commits Specification and the extended rules below. This format enhances clarity, collaboration and automation.

Structure

1. VCS Commit Message

This is the detailed and complete commit message format. It includes:

  • Gitmoji: Emojis to visually represent the type of change.
  • Breaking Changes: Indicate major updates or backward-incompatible changes.
  • Footers: Metadata for tracking.

Framework:

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

<body>

BREAKING CHANGE: <breaking-change>
<footer-header>: <footer-value>
<footer-header>: <footer-value>

2. Work Log Message

A simpler commit message for internal or quick documentation purposes. It excludes:

  • Gitmoji
  • Footers
  • Breaking Changes

Framework:

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

<body>

Message Components

Gitmoji

  • Indicates the purpose or nature of the overall change
  • If there is multiple changes, will be selected based on type of change ranked highest.
  • Check below Gitmoji List for gitmoji related keywords
  • Only use code. Like, :art:, :rocket:, ....

Type

  • Indicates the purpose or nature of the change.
  • Must be one of the following:
    • feat: New feature.
    • fix: Bug fix.
    • docs: Documentation updates.
    • style: Code style changes.
    • refactor: Refactoring code.
    • perf: Performance improvements.
    • test: Adding or modifying tests.
    • build: Changes to build system or dependencies.
    • ci: CI/CD pipeline changes.
    • chore: Routine tasks or maintenance.
    • revert: Reverting a previous commit.

Scope

  • Follows kebab case
  • Specifies the affected area of the codebase
  • If multiple areas detected, try to make a short slug that overall indicates the scope
  • Examples: auth, dashboard, api, frontend, backend

Subject

  • A concise summary of the change
  • Try to keep within 50 characters, max cap 72 characters
  • Don't end with period
  • Must be sentence case
  • Written in the imperative mood (e.g., Fix, not Fixed / Fixes etc.). Example:
    Good Bad Very Bad
    Refactor subsystem X for readability Fixed bug with Y More fixes for broken stuff
    Update getting started documentation Changing behavior of X Sweet new API methods
    Remove deprecated methods 42
    Release version 1.0.0
  • Standard terminology
    First Word Meaning
    Add Create a capability e.g. feature, test, dependency.
    Cut Remove a capability e.g. feature, test, dependency.
    Fix Fix an issue e.g. bug, typo, accident, misstatement.
    Bump Increase the version of something e.g. dependency.
    Make Change the build process, or tooling, or infra.
    Start Begin doing something; e.g. create a feature flag.
    Stop End doing something; e.g. remove a feature flag.
    Refactor A code change that MUST be just a refactoring.
    Reformat Refactor of formatting, e.g. omit whitespace.
    Optimize Refactor of performance, e.g. speed up code.
    Document Refactor of documentation, e.g. help files.
  • Subject lines must never contain (and / or start with) anything else. Especially not something that's unique to your system, like
    • [bug] ...
    • (release) ...
    • #12345 ...
    • jira://...
    • docs: ...
  • Must be able to complete the sentence:

If applied, this commit will ...

Body

  • Must be wrapped at 72 columns
  • Provides additional context or details about the change
  • Must only contain explanations as to what and why, never how
  • Explain the Background and Reasoning, not the Implementation
  • Use bullet points with hyphens or asterisks, followed by a single space, and apply hanging indents
  • Each item of the list must be postfixed with relevant Gitmoji

Footers

  • Optional metadata for tracking and references.
  • Common keywords (detect based on content difference/changes/differences):
    • Author: Specifies the original author of the commit. (Example: Author: John Doe <[email protected]>)
    • Acked-by: Indicates that the person acknowledges and approves the change but may not have directly reviewed it. (Example: Acked-by: Jane Smith <[email protected]>)
    • Co-authored-by: Used to credit multiple contributors to a commit. Each co-author gets a line. (Example: Co-authored-by: Alice Brown <[email protected]>)
    • Closes: Indicates that the commit resolves or closes a specific issue or bug from a tracker. (Example: Closes: #1234)
    • Implements: Shows that this commit implements a specific feature or functionality described in an issue or design document. (Example: Implements: #5678)
    • Reviewed-by: Notes the reviewer(s) who reviewed the changes. Often used in projects with formal review processes. (Example: Reviewed-by: Mark Lee <[email protected]>)
    • Refs: Refers to related issues, bugs, or other references without necessarily closing or resolving them. ( Example: Refs: #4321)
    • Signed-off-by: Certifies that the contributor agrees to the Developer Certificate of Origin (DCO). Common in open source projects. (Example: Signed-off-by: Emily White <[email protected]>)
    • Tested-by: Indicates that the changes were tested by someone, ensuring functionality or stability. (Example: Tested-by: Tom Green <[email protected]>)
    • Fixes: Indicates that the commit fixes a particular issue or bug. Often used interchangeably with Closes.
      (Example: Fixes: #5432)
    • See: Points to related discussions, issues, or resources without directly linking them to the commit.
      (Example: See: #1357)
    • Reported-by: Credits the person who reported an issue or bug.
      (Example: Reported-by: Sam Wilson <[email protected]>)
    • Suggested-by: Credits someone who suggested the change or feature.
      (Example: Suggested-by: Chris Taylor <[email protected]>)
    • Part-of: Indicates that the commit is part of a larger task, feature, or epic.
      (Example: Part-of: #2468)
    • Depends-on: Specifies that the commit depends on another commit or PR to function correctly.
      (Example: Depends-on: #369)
    • Changelog: Adds specific notes to be included in a changelog.
      (Example: Changelog: Improved performance of search feature.)

Breaking Changes

  • Use BREAKING CHANGE: to signal backward-incompatible changes.
  • Clearly describe the impact and necessary migration steps.
  • Only appliable if there is any breaking changes in code

Meta

  • An optional meta tag field to indicate the commit's status
  • Example Tags: #wip (work in progress) or #irrelevant .....

Example

A. VCS Commit Message:

✨ feat(dashboard): implement drill-down functionality

  • Refactor subsystem X for readability 🎨
  • Add a new feature for user authentication ✨
  • Update the README documentation 📝
  • Remove unused files and dependencies 🔥

BREAKING CHANGE: The data format for drill-down events has been changed.

Refs: #1234

B. Work Log Message:

feat(dashboard): implement drill-down functionality

  • Refactor subsystem X for readability
  • Add a new feature for user authentication
  • Update the README documentation
  • Remove unused files and dependencies

Gitmoji List

Below is a comprehensive table of Gitmoji emojis, their codes, and descriptions:

Emoji Code Description
🎨 :art: Improve structure/format of the code.
⚡️ :zap: Improve performance.
🔥 :fire: Remove code or files.
🐛 :bug: Fix a bug.
🚑️ :ambulance: Critical hotfix.
✨ :sparkles: Introduce new features.
📝 :memo: Add or update documentation.
🚀 :rocket: Deploy stuff.
💄 :lipstick: Add or update the UI and style files.
🎉 :tada: Begin a project.
✅ :white_check_mark: Add, update, or pass tests.
🔒️ :lock: Fix security or privacy issues.
🔐 :closed_lock_with_key: Add or update secrets.
🔖 :bookmark: Release/version tags.
🚨 :rotating_light: Fix compiler/linter warnings.
🚧 :construction: Work in progress.
💚 :green_heart: Fix CI build.
⬇️ :arrow_down: Downgrade dependencies.
⬆️ :arrow_up: Upgrade dependencies.
📌 :pushpin: Pin dependencies to specific versions.
👷 :construction_worker: Add or update CI build system.
📈 :chart_with_upwards_trend: Add or update analytics or track code.
♻️ :recycle: Refactor code.
➕ :heavy_plus_sign: Add a dependency.
➖ :heavy_minus_sign: Remove a dependency.
🔧 :wrench: Add or update configuration files.
🔨 :hammer: Add or update development scripts.
🌐 :globe_with_meridians: Internationalization and localization.
✏️ :pencil2: Fix typos.
💩 :poop: Write bad code that needs to be improved.
⏪️ :rewind: Revert changes.
🔀 :twisted_rightwards_arrows: Merge branches.
📦️ :package: Add or update compiled files or packages.
👽️ :alien: Update code due to external API changes.
🚚 :truck: Move or rename resources (e.g., files, paths, routes).
📄 :page_facing_up: Add or update license.
💥 :boom: Introduce breaking changes.
🍱 :bento: Add or update assets.
♿️ :wheelchair: Improve accessibility.
💡 :bulb: Add or update comments in source code.
🍻 :beers: Write code drunkenly.
💬 :speech_balloon: Add or update text and literals.
🗃️ :card_file_box: Perform database-related changes.
🔊 :loud_sound: Add or update logs.
🔇 :mute: Remove logs.
👥 :busts_in_silhouette: Add or update contributor(s).
🚸 :children_crossing: Improve user experience/usability.
🏗️ :building_construction: Make architectural changes.
📱 :iphone: Work on responsive design.
🤡 :clown_face: Mock things.
🥚 :egg: Add or update an easter egg.
🙈 :see_no_evil: Add or update a .gitignore file.
📸 :camera_flash: Add or update snapshots.
⚗️ :alembic: Perform experiments.
🔍️ :mag: Improve SEO.
🏷️ :label: Add or update types.
🌱 :seedling: Add or update seed files.
🚩 :triangular_flag_on_post: Add, update, or remove feature flags.
🥅 :goal_net: Catch errors.
💫 :dizzy: Add or update animations and transitions.
🗑️ :wastebasket: Deprecate code that needs to be cleaned up.
🛂 :passport_control: Work on code related to authorization, roles, and permissions.
🩹 :adhesive_bandage: Simple fix for a non-critical issue.
🧐 :monocle_face: Data exploration/inspection.
⚰️ :coffin: Remove dead code.
🧪 :test_tube: Add a failing test.
👔 :necktie: Add or update business logic.
🩺 :stethoscope: Add or update healthcheck.
🧱 :bricks: Infrastructure-related changes.
🧑‍💻 :technologist: Improve developer experience.
💸 :money_with_wings: Add sponsorships or money-related infrastructure.
🧵 :thread: Add or update code related to multithreading or concurrency.

Generation Guideline

  • Generate a diff file (e.g. diff.txt) using git diff
  • Review Commit Message & ensure proper formatting
  • Validate Message Structure
  • Ensure clarity, consistency, and adherence to guidelines.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment