A Comprehensive Guide to Using Footers in Conventional Commit Messages

Claudio Ctin3 months ago5 mins

Introduction

Traditional commit messages are a crucial part of maintaining a clean, traceable history in software projects. An important component of these messages is the footer, which serves specific purposes such as identifying breaking changes and referencing issues or pull requests. This guide will walk you through the different types of footers, their nuances, and how to use them effectively.

Structure of a Conventional Commit Message

A typical Conventional Commit message is structured as follows:

 <type>(<scope>): <subject>
 <BLANK LINE>
 <body>
 <BLANK LINE>
 <footer>

Types of Footers

1. Breaking Changes

Purpose: To indicate significant changes that are not backward-compatible.

Example:

BREAKING CHANGE: The API endpoint `/users` has been removed and replaced with `/members`.

2. Issue and Pull Request References

These footers link your commits to issues or pull requests in your project management system.

Fixes / Closes / Resolves

Purpose: To close an issue or pull request when the commit is merged.

Nuances:

Fixes: Typically used when the commit addresses a bug.

Closes: Used to indicate that the work described in the issue or PR is complete.

Resolves: A general term indicating that the commit resolves the mentioned issue or PR.

Examples:

Fixes #123
Closes #456
Resolves #789

Related / References

Purpose: To indicate that the commit is related to, but does not necessarily close, an issue or pull request.

Examples:

Related to #101
References #202

3. Co-authored-by

Purpose: To credit multiple contributors to a single commit.

Example:

Co-authored-by: Jane Doe <jane.doe@example.com>

4. Reviewed-by

Purpose: To acknowledge the person who reviewed the commit.

Example:

Reviewed-by: John Smith <john.smith@example.com>

5. Signed-off-by

Purpose: To indicate that the commit complies with the project’s contribution guidelines, often seen in projects using the Developer Certificate of Origin (DCO).

Example:

Signed-off-by: Alice Johnson <alice.johnson@example.com>

6. See also

Purpose: To reference related issues or pull requests that are relevant to the commit.

Example:

Putting It All Together

Here’s an example of a Conventional Commit message utilizing multiple footer types:

feat(auth): add OAuth2 support

Added support for OAuth2 login to enhance security and user convenience. This includes the implementation of authorization code flow and token management.

BREAKING CHANGE: The old authentication method using API keys has been removed. All clients must now use OAuth2.

Fixes #101
Related to #202
Reviewed-by: John Smith <john.smith@example.com>
Co-authored-by: Jane Doe <jane.doe@example.com>
Signed-off-by: Alice Johnson <alice.johnson@example.com>
See also #303

Conclusion

Using footers in Conventional Commit messages effectively can greatly enhance the clarity and maintainability of your project’s history. By understanding and properly employing footers such as BREAKING CHANGE, Fixes, Closes, Resolves, Related to, Co-authored-by, Reviewed-by, Signed-off-by, and See also, you can ensure that your commits are informative and that your project management tools can automate the handling of issues and pull requests efficiently.

References

Conventional Commits
Developer Certificate of Origin

By following these guidelines, software engineers can maintain a more structured and informative commit history, aiding both current project maintenance and future development efforts.

Please follow and like us: