HackMD
GitOps - Contributing Changes
We would love for you to contribute to our project and help make it even better than it is today! As a contributor, here are the guidelines we would like you to follow:
- Commit Conventions
- GitFlow Feature Branches
- Pull Requests
- Squashing and Rebasing
- Code Reviews
- Code Reviews
- Branch Rules
- Merging (types)
Commit Conventions
We have very precise rules over how our Git commit messages must be formatted. So WHY are specific commit conventions necessary?
With clean, consistent commit conventions projects can auto-generate Release ChangeLog documentation. Generating changelogs quickly and consistently is a critical part of each release.
@see the Google's Angular Changelog
Good commit formats ensures clarity and readable messages that are easy to follow when looking through the project history.
To enforce commit conventions, the following tooling may be used Husky Pre-commit Hooks, and Commitizen CLI. Watch the Egghead Video: Using Commitizen for details.
Commit Message Format
Each commit message consists of a header, a body and a footer.
- The header has a special format that includes a type, a scope and a summary. The header is mandatory and the scope of the header is optional.
- The footer should contain a closing reference to an issue if any.
Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.
We use the git commit messages to generate release notes: CHANGELOG.md
Message Parts
The header is mandatory and must conform to the Commit Message 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 format.
The footer is optional. The Commit Message Footer format describes what the footer is used for and the structure it must have.
Commit Message Header
The <type> and <summary> fields are mandatory, the (<scope>) field is optional.
<Type>
Must be one of the following:
| Option | 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 (example scopes: Circle, BrowserStack, 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 | |
| chore | Changes to project organization, packages, tooling, infrastructure; these changes should NOT show in the changelong | |
| style | Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) |
<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 for this use package name rule:
surveyconsetproxyuii18ntoolsupgradepackagingformsstyles
There are currently a few exceptions to the use package name rule:
- packaging: used for changes that change the npm package layout in all of our packages,
- e.g. public path changes,
- package.json changes done to all packages,
- d.ts file/format changes,
- changes to bundles,
- etc.
- changelog: used for updating the release notes in CHANGELOG.md
- none/empty string: useful for
style,testandrefactorchanges that are done across all packages, and for docs changes that are not related to a specific package.style: add missing semicolonsdocs: fix typo in tutorial
<Summary> (aka Subject)
The subject contains 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
<Body>
Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes".
The body should include the motivation for the change and contrast this with previous behavior.
Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines. The rest of the commit message body is then used for this information.
<Footer>
The footer should contain any information about Breaking Changes and is also the place to
reference GitHub issues that this commit Closes.
Revert
If the commit reverts a previous commit, it should begin with revert: , followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.
For example:
or
Breaking Change section should start with the phrase "BREAKING CHANGE: " followed by a 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.
