Commit Message Guideline

Article: Dec 17, 2024

Clear and consistent commit messages are essential for collaborative development, especially in Dynamics 365 Finance and Operations (D365 FO) projects. They enable:

  • Improved code history readability for current and future teams.
  • Easier troubleshooting.
  • Automated changelog generation for release management.

This guide provides two structured approaches to commit messages:

  1. Type/Scope Format (type(scope): subject)
  2. Problem-Solution Format

Both formats are valid, and teams can choose based on their workflows and priorities.

Structure of a Commit Message

A commit message generally consists of three parts:

<header>

<body>

<footer>

Components

  1. Header: Concise summary of the change.
  2. Body (Optional): Detailed explanation of the change and its purpose.
  3. Footer (Optional): Notes on breaking changes or references to related issues.

General Rules

  • Limit the header line to 50 characters (72 is acceptable but aim for brevity).
  • Use the imperative present tense (e.g., "add," "fix").
  • Do not end the header line with a period.

Teams can select a format based on their needs:

Type/Scope Format

This format is ideal for teams requiring strict consistency or automated changelog generation. It provides clear categorization of changes and enables automation tools to integrate seamlessly.

This format shares similarities with the Angular commit message guidelines.

Header Format (Type/Scope)

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

  • Type: Describes the kind of change. See the allowed types below.
  • Scope: Specifies the module, feature, or area affected. Examples: Sales, Inventory, Pipelines.
  • Subject
    • Summarizes the change in imperative present tense (e.g., "add," "fix").
    • Do not capitalize the first word of the subject line.

Allowed Types

  • build: Changes affecting the build system or external dependencies.
  • ci: Changes to CI configuration files and scripts.
  • docs: Documentation-only changes.
  • feat: A new feature.
  • fix: A bug fix.
  • perf: A code change that improves performance.
  • refactor: A code change that neither fixes a bug nor adds a feature.
  • test: Adding or correcting tests.
  • revert
    • If the commit reverts a previous commit, it should begin with revert:, followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.

Allowed Scopes

Scopes should follow a predefined list for consistency. Examples:

  • Use the module name for changes specific to a module.
  • Use a business process for broader changes.
  • Use * for changes affecting multiple modules or areas.

Examples (Type/Scope)

New Feature

feat(CustomerAccountsPayable): add early payment discount logic

Bug Fix

fix(CustomerIntegrationShopify): resolve duplicate order imports

Problem-Solution Format

This format emphasizes describing the problem and its resolution. It is more flexible and suitable for smaller projects or teams prioritizing readability.

Header Format (Problem-Solution)

<header>

  • Aim to describe the value of the change clearly and concisely.
  • Use the body to explain complex changes for future readers.

Examples (Problem-Solution)

New Feature

Add support for multi-tier pricing in Sales module

Bug Fix

Fix VAT calculation error in Accounts Payable

Body (Optional)

The body provides additional context and should:

  • Explain why the change was necessary.
  • Describe what has been fixed, added, or improved.
  • Highlight differences between the old and new behavior.
  • Limit lines to 72 characters for readability in Git tools.

Example Body

<header>

The new functionality introduces batch tracking for inventory items, 
allowing users to monitor specific batches throughout the supply chain. 
This change improves traceability and compliance with regulatory 
requirements but requires adjustments to existing custom integrations.

<footer>

The footer provides supplementary information:

  • Breaking changes should be prefixed with BREAKING CHANGE: and describe major changes requiring updates to integrations or dependent systems.
  • References to related issues should be linked using the format Closes #<issue-number>.
<header>

<body>

BREAKING CHANGE: Batch tracking now requires additional fields in the 
InventoryBatch table. Ensure all custom integrations are updated to 
include the BatchID parameter.

Closes #712, #713