mirror of
https://github.com/angular/angular
synced 2026-05-24 09:28:37 +00:00
4739bde9fb
Fix various typos, misspellings, and grammar issues across contributing docs, adev content guides, and agent skills documentation. - "an minimum" → "a minimum" (CONTRIBUTING.md) - "GitHub accounts" → "GitHub account" (CONTRIBUTING.md) - "decendants" → "descendants" (components/styling.md) - "templates are using" → "templates is using" (hydration.md) - "A automated" → "An automated" (branches-and-versioning.md) - "Github" → "GitHub" (branches-and-versioning.md, commit-message-guidelines.md) - "practices makes" → "practice makes" (caretaking.md) - "corresponds" → "correspond" (triage-and-labelling.md) - "one a line" → "a line" (documentation-authoring.md) - "straight forward" → "straightforward" (using-fixup-commits.md) - "or you decide" → "or you can decide" (anatomy-of-components.md) - "whenver" → "whenever" (angular-new-app/SKILL.md)
152 lines
6.3 KiB
Markdown
152 lines
6.3 KiB
Markdown
# 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#
|