Creating Quality Commit Messages - NCIOCPL/ncids GitHub Wiki

The NCIDS must maintain quality commit messages to ensure intuitive release notes. By following these guidelines, we can ensure clear communication and better collaboration among team members.

Commit message template

When making a commit to the design system project, please follow this template for creating commit messages:

(#TICKET-NUMBER) Brief description of the change

- Additional work needed to complete PR too small for its own commit
- Any relevant information or context

Closes #TICKET-NUMBER

Guidelines for quality commit messages

  1. Include ticket number: Start your commit message with the ticket number in parentheses to link it to the corresponding ticket in GitHub.

  2. Use action words: Write the subject of your commit in the commit title, indicating what action (e.g., update, add, fix, remove) the commit will preform if merged to the repository.

    A properly formed Git commit subject line should always be able to complete the following sentence: If applied, this commit will your [describe the impact here] For example:

    • If applied, this commit will [refactor subsystem X for readability]
    • If applied, this commit will [update getting started documentation]
    • If applied, this commit will [remove deprecated methods]
    • If applied, this commit will [release version 1.0.0]
    • If applied, this commit will [merge pull request #123 from user/branch]

    Avoid vague commit titles that do not convey the purpose of the change, notice how they make it confusing or harder to understand the purpose of the commit at-glance:

    • If applied, this commit will [more fixes for broken stuff]
    • If applied, this commit will [sweet new API methods]

  3. Provide details: Use bullet points in the commit description to list any additional work required to complete the ticket and any relevant information or context about the changes made.

  4. Closing the ticket: End the commit message with Closes #TICKET-NUMBER to mark the ticket as completed on merge.

Example

(#123) Update button styles

- Adjust button icon alignment to match USWDS styling
- Update documentation site to include missing examples

Closes #123

Further reading