Committing Code to Spartacus
We use git commit messages to generate the framework changelog. To that end, we have specific rules for how to format git commit messages. These rules are also intended to make the commit messages easier to read.
Table of Contents
If you are on Windows, set the Git
core.autocrlf configuration property to “false”, and make sure to use Unix-style linebreaks (LF-only).
When you are ready to merge your pull request, select GitHub’s
Squash and merge option, as shown in the following image:
For information on
Squash and merge, see GitHub Help.
Commit Message Format
The commit message consists of a header, a body, and optionally, a footer. Each line in the commit message has a maximum length of 100 characters.
When you click
Squash and merge, two text fields appear. The first is for entering the header, and the second is for entering the body and footer, as shown in the following screenshot:
The following is an example of a header you might enter:
feat: introduce new facade signature and generic ngrx store state for fine-grained control of loading state (#124)
The following is an example of the corresponding body and footer. The footer begins with
BREAKING CHANGE. Note that the body and footer are separated by a blank line:
The product, language and currency facades have been refactored. A generic reducer has been introduced for all entities that require fine-grained load, success and error state. BREAKING CHANGE: Product, language and currency facades have a new public interface. Closes #123
The commit header is a brief summary of the work done.
When you click
Squash and merge, the header field is automatically populated. However, it does not match our commit guidelines format precisely. Please modify it to fit the following format:
<type>: <subject> (PR number)
type is mandatory, and must be one of the following:
docs: for changes to documentation only
feat: for new feature work
fix: for a bug fix
perf: for a code change that improves performance
refactor: for a code change that neither fixes a bug nor adds a feature
style: for changes that do not affect the meaning of the code, such as white-space, formatting, missing semi-colons, and so on
test: for adding missing tests or to correct existing tests.
chore: for changes related to builds, CI, scripts, configs, and anything that does not fit any of the types above.
In the changelog, we only include commits that are of type
The subject contains a succinct description of the change, and adheres to the following rules:
- The subject is written in the present, imperative tense. For example, “add facades”, rather than “adds facades” or “added facades”.
- The first letter of the subject message is in lower-case.
- There is no period at the end of the subject message.
At the end of the header, include the GitHub PR number in parentheses, as follows:
By default, GitHub includes the pull request number automatically here, so you do not need to add this manually. After your commit message is submitted, GitHub converts the PR number into a link to the original pull request, which can be convenient for anyone who is reading the changelog.
The body is entered in the text field below the header field.
The following are some guidelines for writing the body:
Describe the problem you are fixing. Whether your patch is a one-line bug fix, or is 5000 lines of new code, there must be an underlying problem that motivated you to do this work. Make the necessity of the fix clear to the reviewers, so they will continue reading.
Describe the effect that this change has from a user’s point of view. App crashes and lockups are pretty convincing, but not all bugs are that obvious; this information should be mentioned in the text. Even if the problem was spotted during code review, describe the impact you think it can have on users.
Describe the technical details of what you changed. It is important to describe the change as clearly as possible. This will help the reviewer to verify that the code is behaving as you intend it to.
If your issue contains a breaking change, start the footer with
BREAKING CHANGE: followed by a space or an empty line, and then a description of the breaking change. You can indicate one or more breaking changes in the footer with the following keywords:
If your issue contains a deprecation, you use a similar approach to breaking changes, with the following keywords:
The footer is also the place where you should reference the issue you are fixing (for example,
closes #123 or
fixes #123). For information on the format, and a list of the available keywords, see GitHub Help. Additionally, it will automatically close your issue once you merge your PR to the default repository branch.
Reverting a Commit
If your commit reverts a previous commit, begin the header with
revert: and then include the header of the reverted commit. In the body, write “This reverts commit hash”, where hash is the SHA of the commit you are reverting.