diff options
Diffstat (limited to 'docs/commit-message-guidelines.md')
| -rw-r--r-- | docs/commit-message-guidelines.md | 152 |
1 files changed, 152 insertions, 0 deletions
diff --git a/docs/commit-message-guidelines.md b/docs/commit-message-guidelines.md new file mode 100644 index 0000000..709e830 --- /dev/null +++ b/docs/commit-message-guidelines.md @@ -0,0 +1,152 @@ +# Commit Message Format + +We have very precise rules over how our Git commit messages must be formatted. +This format leads to **easier to read commit history** and makes it analyzable for changelog generation. + +Each commit message consists of a **header**, a **body**, and a **footer**. + +``` +<header> +<BLANK LINE> +<body> +<BLANK LINE> +<footer> +``` + +The `header` is mandatory and must conform to the [Commit Message Header](#commit-header) format. + +The `body` is mandatory for all commits except for those of type "docs". +When the body is present it must be at least 20 characters long and must conform to the [Commit Message Body](#commit-body) format. + +The `footer` is optional. The [Commit Message Footer](#commit-footer) format describes what the footer is used for and the structure it must have. + +## <a name="commit-header"></a>Commit Message Header + +``` +<type>(<scope>): <short summary> + │ │ │ + │ │ └─⫸ Summary in present tense. Not capitalized. No period at the end. + │ │ + │ └─⫸ Commit Scope: animations|bazel|benchpress|common|compiler|compiler-cli|core| + │ elements|forms|http|language-service|localize|platform-browser| + │ platform-browser-dynamic|platform-server|router|service-worker| + │ upgrade|zone.js|packaging|changelog|docs-infra|migrations| + │ devtools + │ + └─⫸ Commit Type: build|ci|docs|feat|fix|perf|refactor|test +``` + +The `<type>` and `<summary>` fields are mandatory, the `(<scope>)` field is optional. + +### Type + +Must be one of the following: + +| Type | Description | +| ------------ | --------------------------------------------------------------------------------------------------- | +| **build** | Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) | +| **ci** | Changes to our CI configuration files and scripts (examples: Github Actions, SauceLabs) | +| **docs** | Documentation only changes | +| **feat** | A new feature | +| **fix** | A bug fix | +| **perf** | A code change that improves performance | +| **refactor** | A code change that neither fixes a bug nor adds a feature | +| **test** | Adding missing tests or correcting existing tests | + +### <a name="scope"></a> Scope + +The scope should be the name of the npm package affected (as perceived by the person reading the changelog generated from commit messages). + +The following is the list of supported scopes: + +- `animations` +- `benchpress` +- `common` +- `compiler` +- `compiler-cli` +- `core` +- `dev-infra` +- `devtools` +- `docs-infra` +- `elements` +- `forms` +- `http` +- `language-service` +- `language-server` +- `localize` +- `migrations` +- `platform-browser` +- `platform-browser-dynamic` +- `platform-server` +- `router` +- `service-worker` +- `upgrade` +- `vscode-extension` +- `zone.js` + +There are currently a few exceptions to the "use package name" rule: + +- `dev-infra`: used for dev-infra related changes within the directories /scripts and /tools + +- `docs-infra`: used for infrastructure changes to the docs-app (angular.dev) within the `/adev` directory, such as application code, tooling, or configuration. **For modifications to documentation content (e.g., editing a `.md` file), use `docs:` without a scope instead.** + +- `migrations`: used for changes to the `ng update` migrations. + +- `devtools`: used for changes in the [browser extension](../devtools/README.md). + +- none/empty string: useful for `test` and `refactor` changes that are done across all packages (e.g. `test: add missing unit tests`) and for docs changes that are not related to a specific package (e.g. `docs: fix typo in tutorial`). + +### Summary + +Use the summary field to provide a succinct description of the change: + +- use the imperative, present tense: "change" not "changed" nor "changes" +- don't capitalize the first letter +- no dot (.) at the end + +## <a name="commit-body"></a>Commit Message Body + +Just as in the summary, use the imperative, present tense: "fix" not "fixed" nor "fixes". + +Explain the motivation for the change in the commit message body. This commit message should explain _why_ you are making the change. +You can include a comparison of the previous behavior with the new behavior in order to illustrate the impact of the change. + +## <a name="commit-footer"></a>Commit Message Footer + +The footer can contain information about breaking changes and deprecations and is also the place to reference GitHub issues and other PRs that this commit closes or is related to. +For example: + +``` +BREAKING CHANGE: <breaking change summary> +<BLANK LINE> +<breaking change description + migration instructions> +<BLANK LINE> +<BLANK LINE> +Fixes #<issue number> +``` + +or + +``` +DEPRECATED: <what is deprecated> +<BLANK LINE> +<deprecation description + recommended update path> +<BLANK LINE> +<BLANK LINE> +Closes #<pr number> +``` + +Breaking Change section should start with the phrase `BREAKING CHANGE: ` followed by a _brief_ summary of the breaking change, a blank line, and a detailed description of the breaking change that also includes migration instructions. + +Similarly, a Deprecation section should start with `DEPRECATED: ` followed by a short description of what is deprecated, a blank line, and a detailed description of the deprecation that also mentions the recommended update path. + +## Revert commits + +If the commit reverts a previous commit, it should begin with `revert: `, followed by the header of the reverted commit. + +The content of the commit message body should contain: + +- information about the SHA of the commit being reverted in the following format: `This reverts commit <SHA>`, +- a clear description of the reason for reverting the commit message. + +[angularjs-commit-message-format]: https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit# |