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:
See also #321
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
By following these guidelines, software engineers can maintain a more structured and informative commit history, aiding both current project maintenance and future development efforts.
Top comments (0)