|
| 1 | +<div align="center"> |
| 2 | +<h1>Shareable Commitlint Configuration</h1> |
| 3 | + |
| 4 | +A shareable commitlint configuration for enforcing consistent commit messages in your projects. |
| 5 | + |
| 6 | +[![npm-image]][npm-url] [![license-image]][license-url] |
| 7 | + |
| 8 | +</div> |
| 9 | + |
| 10 | +--- |
| 11 | + |
| 12 | +<div align="center"> |
| 13 | + <p> |
| 14 | + <sup> |
| 15 | + Daniel Bannert's open source work is supported by the community on <a href="https://github.com/sponsors/prisis">GitHub Sponsors</a> |
| 16 | + </sup> |
| 17 | + </p> |
| 18 | +</div> |
| 19 | + |
| 20 | +--- |
| 21 | + |
| 22 | +## Purpose |
| 23 | + |
| 24 | +- Ensure a cohesive structure for all commits in your project with a comprehensive set of rules. |
| 25 | +- Consistency in commit messages plays a pivotal role in fostering effective project collaboration, enhancing maintainability, and preserving project history. |
| 26 | +- By leveraging commitlint configuration, you can effortlessly enforce a standardized structure for all commits in your project. |
| 27 | +- This valuable tool facilitates better comprehension of the changes made and the reasoning behind them, enabling seamless understanding for your entire team. |
| 28 | +- This configuration also includes a semantic-release configuration, which enables automated GitHub/NPM releases based on your commit messages. |
| 29 | + |
| 30 | +## Install |
| 31 | + |
| 32 | +```bash |
| 33 | +npm install --dev-save @commitlint/cli @anolilab/commitlint-config |
| 34 | +``` |
| 35 | + |
| 36 | +```sh |
| 37 | +yarn add -D @commitlint/cli @anolilab/commitlint-config |
| 38 | +``` |
| 39 | + |
| 40 | +```sh |
| 41 | +pnpm add -D @commitlint/cli @anolilab/commitlint-config |
| 42 | +``` |
| 43 | + |
| 44 | +## Usage |
| 45 | + |
| 46 | +When installing this package for the first time, the following shareable configuration `commitlint.config.js` is automatically added to your project folder: |
| 47 | + |
| 48 | +> Note: If the script detects an existing `commitlint.config.js` file, it will not overwrite it. |
| 49 | +
|
| 50 | +> Note: It can happen that the postinstall script dont run, then you have to add the `commitlint.config.js` manually. |
| 51 | +
|
| 52 | +```js |
| 53 | +module.exports = { |
| 54 | + extends: ['@anolilab/commitlint-config'], |
| 55 | + rules: { |
| 56 | + // overwrite rules here |
| 57 | + // or extend rules |
| 58 | + }, |
| 59 | +}; |
| 60 | +``` |
| 61 | +or |
| 62 | + |
| 63 | +```js |
| 64 | +export default { |
| 65 | + extends: ['@anolilab/commitlint-config'], |
| 66 | + rules: { |
| 67 | + // overwrite rules here |
| 68 | + // or extend rules |
| 69 | + }, |
| 70 | +}; |
| 71 | +``` |
| 72 | + |
| 73 | +This extends the `@anolilab/commitlint-config` and uses its pre-defined configuration. |
| 74 | + |
| 75 | +> Alternatively the configuration can be defined in a `commitlint.config.js`, `.commitlintrc.js`, `.commitlintrc`, `.commitlintrc.json`, `.commitlintrc.yml` file |
| 76 | +
|
| 77 | +## Commitlint Rules |
| 78 | + |
| 79 | +The following customized rules are included in this configuration: |
| 80 | + |
| 81 | +- `body-leading-blank`: There must be a blank line between the subject and the body. |
| 82 | +- `body-max-line-length`: The body must not exceed 100 characters per line. |
| 83 | +- `footer-leading-blank`: There must be a blank line between the body and the footer. |
| 84 | +- `footer-max-line-length`: The footer must not exceed 100 characters per line. |
| 85 | +- `header-max-length`: The header must not exceed 100 characters per line. |
| 86 | +- `scope-case`: The scope must be lowercase and use kebab-case. |
| 87 | +- `scope-empty`: The scope is optional. |
| 88 | +- `subject-case`: The subject must start with a capital letter and use sentence case. |
| 89 | +- `subject-empty`: The subject is required. |
| 90 | +- `subject-full-stop`: The subject must not end with a period. |
| 91 | +- `type-case`: The type must be lowercase. |
| 92 | +- `type-empty`: The type is required. |
| 93 | +- `type-enum`: The type must be one of the following: |
| 94 | + - `build`: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) |
| 95 | + - `chore`: Changes to the build process or auxiliary tools and libraries such as documentation generation |
| 96 | + - `ci`: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs) |
| 97 | + - `deps`: Changes that add, update, or remove dependencies |
| 98 | + - `docs`: Documentation only changes |
| 99 | + - `feat`: A new feature |
| 100 | + - `fix`: A bug fix |
| 101 | + - `perf`: A code change that improves performance |
| 102 | + - `refactor`: A code change that neither fixes a bug nor adds a feature |
| 103 | + - `revert`: Reverts a previous commit |
| 104 | + - `security`: A code change that improves security |
| 105 | + - `style`: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) |
| 106 | + - `test`: Adding missing tests or correcting existing tests |
| 107 | + - `translation`: Translation changes |
| 108 | + |
| 109 | +and all rules from [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional). |
| 110 | + |
| 111 | +## Add a Package.json Script |
| 112 | + |
| 113 | +To add an NPM script for running `commitlint` use command, which will add the `lint:commits` script to the scripts section of your `package.json`. |
| 114 | + |
| 115 | +```bash |
| 116 | +pnpm pkg set scripts.lint:commits="pnpm commitlint --from HEAD~1 --to HEAD --verbose" |
| 117 | +``` |
| 118 | + |
| 119 | +> For `npm` users, replace `pnpm` with `npm` in the above command. |
| 120 | +
|
| 121 | +## Husky |
| 122 | + |
| 123 | +### Install |
| 124 | + |
| 125 | +```bash |
| 126 | +pnpm add -D husky is-ci |
| 127 | +``` |
| 128 | + |
| 129 | +To add a `commit-msg` hook to your project, run the following command: |
| 130 | + |
| 131 | +```bash |
| 132 | + npx husky add .husky/commit-msg 'pnpm commitlint --edit "${1}"' |
| 133 | +``` |
| 134 | + |
| 135 | +And for `package.json`: |
| 136 | + |
| 137 | +```bash |
| 138 | +pnpm pkg set scripts.prepare="is-ci || husky install" |
| 139 | +``` |
| 140 | + |
| 141 | +> For `npm` users, replace `pnpm` with `npm` in the above command. |
| 142 | +
|
| 143 | +## Test the configuration |
| 144 | + |
| 145 | +For a first simple usage test of commitlint you can do the following: |
| 146 | + |
| 147 | +```bash |
| 148 | +# using pnpm |
| 149 | +$ pnpm commitlint --from HEAD~1 --to HEAD --verbose |
| 150 | + |
| 151 | +# or, using npx |
| 152 | +$ npx commitlint --from HEAD~1 --to HEAD --verbose |
| 153 | + |
| 154 | +# or, if script was added |
| 155 | +$ pnpm lint:commits |
| 156 | +``` |
| 157 | + |
| 158 | +This will check your last commit and return an error if invalid or a positive output if valid. |
| 159 | + |
| 160 | +### Test the hook |
| 161 | + |
| 162 | +You can test the hook by simply committing. If the commit message is valid, the commit will go through, otherwise you will see an error message. |
| 163 | + |
| 164 | +Here's an example of what the error message would look like if your commit message doesn't meet the required format: |
| 165 | + |
| 166 | +```bash |
| 167 | +$ git commit -m "foo: this will fail" |
| 168 | +husky > commit-msg (node v10.1.0) |
| 169 | +No staged files match any of provided globs. |
| 170 | +⧗ input: foo: this will fail |
| 171 | +✖ type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test] [type-enum] |
| 172 | + |
| 173 | +✖ found 1 problems, 0 warnings |
| 174 | +ⓘ Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint |
| 175 | + |
| 176 | +husky > commit-msg hook failed (add --no-verify to bypass) |
| 177 | +``` |
| 178 | + |
| 179 | +If your commit message meets the required format, you should see a message like this: |
| 180 | + |
| 181 | +```bash |
| 182 | +$ git commit -m "feat: add new feature" |
| 183 | +husky > commit-msg (node v10.1.0) |
| 184 | +[master 9d41607] feat: add new feature |
| 185 | + 1 file changed, 1 insertion(+) |
| 186 | +``` |
| 187 | + |
| 188 | +## Supported Node.js Versions |
| 189 | + |
| 190 | +Libraries in this ecosystem make the best effort to track |
| 191 | +[Node.js’ release schedule](https://nodejs.org/en/about/releases/). Here’s [a |
| 192 | +post on why we think this is important](https://medium.com/the-node-js-collection/maintainers-should-consider-following-node-js-release-schedule-ab08ed4de71a). |
| 193 | + |
| 194 | +Contributing |
| 195 | +------------ |
| 196 | + |
| 197 | +If you would like to help take a look at the [list of issues](https://github.com/anolilab/javascript-style-guide/issues) and check our [Contributing](.github/CONTRIBUTING.md) guild. |
| 198 | + |
| 199 | +> **Note:** please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. |
| 200 | +
|
| 201 | +Credits |
| 202 | +------------- |
| 203 | + |
| 204 | +- [Daniel Bannert](https://github.com/prisis) |
| 205 | +- [All Contributors](https://github.com/anolilab/javascript-style-guide/graphs/contributors) |
| 206 | + |
| 207 | +License |
| 208 | +------------- |
| 209 | + |
| 210 | +The anolilab javascript-style-guide is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT) |
| 211 | + |
| 212 | +[1]: https://github.com/semantic-release/commit-analyzer |
| 213 | +[2]: https://github.com/semantic-release/release-notes-generator |
| 214 | +[3]: https://github.com/semantic-release/changelog |
| 215 | +[4]: https://github.com/semantic-release/github |
| 216 | +[5]: https://github.com/semantic-release/exec |
| 217 | +[6]: https://github.com/semantic-release/git |
| 218 | +[7]: https://github.com/semantic-release/npm |
| 219 | + |
| 220 | +[license-image]: https://img.shields.io/npm/l/@anolilab/semantic-release-preset?color=blueviolet&style=for-the-badge |
| 221 | +[license-url]: LICENSE.md "license" |
| 222 | +[npm-image]: https://img.shields.io/npm/v/@anolilab/semantic-release-preset/latest.svg?style=for-the-badge&logo=npm |
| 223 | +[npm-url]: https://www.npmjs.com/package/@anolilab/semantic-release-preset/v/latest "npm" |
0 commit comments