A Comprehensive Guide to Using Footers in Conventional Commit Messages
Tags: git, versioncontrol, softwareengineering, conventionalcommits
Published: 2024-06-18 02:04:58

### 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
- [Conventional Commits](https://www.conventionalcommits.org/)
- [Developer Certificate of Origin](https://developercertificate.org/)
- [Example Shell Script for Setting Up Husky](https://gist.github.com/mochafreddo/7fc9b608869ff3bceae9a89b16479998)

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