# Commit message standards

In order to facilitate interoperability between automated tooling while also maximizing commit message clarity and usefulness, we adhere to conventional commit message standards, with some allowance for MidFirst-specific opinions.

A conventional commit is a structured commit message that concisely conveys the intent and content of a code change. It follows a standardized format that, when adhered to, enables automated tools like semantic-release to manage release versions and effectively generate useful changelogs while also providing clean, useful commit history that is informative to stakeholders.

# Commit message header

The commit header is the first line of the commit message. It includes the type, scope, and a short description of the commit:

<type>(<scope>): <summary>
  │       │    │      │  
  │       │    │      └─⫸ Summary in present tense and imperative mood
  │       │    │           The first word should be capitalized and it should have no period at the end
  │       │    │
  │       │    └─⫸ REQUIRED terminal colon and space            
  │       │
  │       └─⫸ Commit Scope: CERT-123|ui|common|compiler|some-page|component-name
  │                          * Important: When present, use the JIRA ticket number
  │
  └─⫸ Commit Type: feat|fix|docs|test|build|ci|perf|refactor

Type: Indicates the kind of change that the commit represents (e.g. feat, fix, docs)
Scope: A keyword that signifies the part of the codebase affected (e.g. ui, server)
Summary: A brief summary of the change contained in the commit

# Commit type

The type is the most important component of the commit message header. It determines the impact of the commit on the semantic version number and it must be one of the following:

Type	Version Impact	Description
`feat`	MINOR	A new feature
`fix`	PATCH	A bug fix
`perf`	PATCH	A code change that improves performance
`build`	None	Changes that affect the build system or external dependencies
`chore`	None	Changes to the build process or auxiliary tools and libraries such as documentation generation
`ci`	None	Changes to our CI configuration files and scripts
`docs`	None	Documentation only changes
`refactor`	None	A code change that neither fixes a bug nor adds a feature
`revert`	None	Reverts a previous commit
`style`	None	Changes that do not affect the meaning of the code (white-space, formatting, etc.)
`test`	None	Adding missing tests or correcting existing tests

# Commit scope

The scope in a conventional commit message refers to a noun that describes a section of the codebase impacted by the changes. It provides additional contextual information about the commit and is included within parentheses after the type. In the majority of cases, the scope should be a Jira issue number that details the change.

The following are several common examples of commit message scopes. If a particular scope should only be used with a particular commit type, it will be indicated in the Commit Type column.

Scope	Description	Commit Type
`CERT-123`	If Jira Issue exists, use it over any other scope listed Changes that are described by the Jira issue which all of the details the commit should contain	Any
`build`	Changes that affect the build system or external dependencies	`build`
`ci`	Changes to CI configuration files and scripts	`ci`
`config`	Configuration file changes	Any
`core`	Changes related to the core functionality of the application	Any
`deps`	Updates to dependencies	`chore`
`docs`	Documentation changes	`docs`
`perf`	Performance improvements	`perf`
`refactor`	Code changes that neither fix a bug nor add a feature	`refactor`
`revert`	Reverting a previous commit	`revert`
`styles`	Changes that do not affect the meaning of the code (white-space, formatting, etc.)	`style`
`test`	Adding or updating tests	`test`
`ui`	Updates or changes to the user interface	Any

# Commit summary

The summary of a conventional commit message is a concise description that captures the essence of the changes made in the commit.

Because commit messages are used by semantic-release to generate changelogs and perform semantic-versioning, it is important to ensure that they are suitable for public viewing and adhere to the following constraints:

Use present tense and imperative mood

Write the summary in the imperative, present tense

change not changed nor changes
add not added nor adds
correct not corrected nor corrects

Be concise

Keep the summary brief and to the point, ideally under 50 characters. This helps ensure it is easily readable in various interfaces.

Capitalize the first letter

Start the summary with a capital letter.

Avoid ending with a period

Do not end the summary with a period

Focus on what and why

Emphasize what the change is and why it is being made, rather than how it was done.

# Commit message examples

# Feature commits

The following commit suggests that a new Foreclosure module has been implemented and details can be found in the two Jira issues referenced.

git commit -m "feat(CERT-51, CERT-52): Foreclosure module implementation"

This next commit message indicates the addition of a new feature, specifically two-factor authentication (2FA) support, to the login functionality.

git commit -m "feat(login): Add 2FA support"

# Bug fix

This commit message communicates that a bug has been fixed in the network module, addressing an issue where socket connections were not being properly closed.

git commit -m "fix(network): Resolve socket leakage issue"

This commit message communicates that a bug has been fixed where the list-item 'APP' had the incorrect key in the app-switcher.

git commit -m "fix(app-switcher): Correct key for APP list item"

# Performance improvement

This commit message suggests that there has been a performance enhancement to the summary page of the application, by removing navigation properties on the entity which often increases complexity of SQL Calls.

git commit -m "perf(summary): Optimize summary page by removing navigation property from entity"

# Breaking change

This commit message warns of a breaking change where the user API endpoint structure has been redesigned, potentially impacting compatibility with existing integrations.

git commit \
-m "feat(api): Redesign user endpoint structure" \
-m "BREAKING CHANGE: The user API endpoints have been redesigned, which may affect existing integrations."

# Semantic versioning

Semantic versioning is a versioning scheme that communicates the level of compatibility between releases at a glance.

The semantic versioning system uses a three-part numbering system: .. (e.g. 1.22.3)

MAJOR version increments when you make incompatible, breaking changes
MINOR version increments when you add functionality in a backward-compatible manner
PATCH version increments when you make backward-compatible bug fixes

The most important component of the commit header in semantic release is the type, as it determines which component of the version number will be incremented.

The type defined in the commit header has the following impact:

Header Type	Result
fix, perf	Bump version to the next patch level (1.0.0 -> 1.0.1) and release
feat	Bump version to the next minor level (1.0.0 -> 1.1.0) and release
docs, build, ci, refactor, test	No version bump. No release.

Regardless of the header type, if the footer of the commit message contains the string "BREAKING CHANGE" or "DEPRECATED", semantic release will perform MAJOR version increase. See the breaking change example for more details.

# Powering Semantic Release

Commit messages provide the semantics that are used to power semantic versioning for an application when using semantic-release.

Commit message analysis: Semantic-release analyzes commit messages that adhere to conventional format described on this guide, such as fix: for bug fixes or feat: for new features.
Version determination: Based on the types of commits (fix, feat, or BREAKING CHANGE) in a release semantic-release automatically determines the next version number, following the Semantic Versioning (MAJOR.MINOR.PATCH) format.
Changelog generation: It generates a changelog that documents the changes, leveraging the structured commit messages to create a detailed and understandable log.

This process ensures that the application’s versioning is consistent, predictable, and communicates the impact of changes to users, developers, and other stakeholders.

# Additional Resources

The following are helpful resources for more information about Semantic Release and conventional commit messages.