FLOCX Commit Message Best Practices

Commits to FLOCX projects should follow these best practices:

  1. A commit messages should have a subject line and body separated by a blank line.

The first line of your commit message is displayed by itself in various circumstances (e.g., git log --oneline, variously on GitHub, and so forth. The subject should provide a succinct summary of the commit in order to make these displays useful.

  1. The subject message should be limited to 60 characters or less.

The subject line should be kept short, since it is often displayed on screen after a commit id.

  1. The subject line should start with a capital letter.

Readers generally expect the first word in a sentence to be capitalized.

  1. The subject line should not end with a period.

This is a common convention for summary descriptions in many situations.

  1. The subject line should be written in the imperative mood.

  2. Instead of: This commit adds tests for the api class

    Use: Add tests for the api class

  3. Instead of: New widget feature

    Use: Implement new widget feature

  4. Lines in the body should be wrapped at 72 characters.

Many terminals default to 80 characters in width. Keeping lines wrapped at 72 characters leaves room for git to indent messages without overflowing the width of the terminal.

  1. The commit message should explain the purpose of the commit.

We want the git log to be a useful source of information about the project. Your commit message should explain why you made the changes and should summarize the nature of the changes. For example, this isn't a great commit message:

text New configuration code

This is a better one:

```text Add standard configuration handling code (TG-1234)

In order to operate properly, our service requires a number of configuration values to be provided by the operator. This commit introduces a standard mechanism for handling configuration options (oslo_config) and defines a number of configuration options. ```

  1. The commit message should reference the bug/issue/task/user story to which it applies.

Referencing the related bug/issue/etc in your commit message provides information about why the changes were made. In many situations, the reference can be used to automatically update the referenced issue with information about the commit or even apply status changes.

For GitHub issues, use the format #nnn, where nnn is the GitHub issue number. For more information, see Closing issues using keywords.

For Taiga tasks/user stories, use the format TG-nnn, where nnn is the task or user story number. For more information, see Attach commits to elements via commit message and Changing elements status via commit message.