Skip to content

Commit dcecf9d

Browse files
marioneblmarionebl
committed
docs: add guides
1 parent e59874e commit dcecf9d

21 files changed

+412
-199
lines changed

‎@commitlint/cli/scripts/lint:commits.sh

-24
This file was deleted.

‎@commitlint/example-prompt/package.json

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
{
2+
"name": "@commitlint/example-prompt",
3+
"private": true,
4+
"version": "3.0.0",
5+
"description": "Example for prompt guide",
6+
"scripts": {
7+
"commit": "commit"
8+
},
9+
"repository": {
10+
"type": "git",
11+
"url": "git+https://github.com/marionebl/commitlint.git"
12+
},
13+
"author": "Mario Nebl <[email protected]>",
14+
"license": "MIT",
15+
"bugs": {
16+
"url": "https://github.com/marionebl/commitlint/issues"
17+
},
18+
"homepage": "https://github.com/marionebl/commitlint#readme",
19+
"devDependencies": {
20+
"@commitlint/prompt-cli": "^3.0.0"
21+
}
22+
}

‎changelog.md

-4
Original file line numberDiff line numberDiff line change
@@ -318,7 +318,3 @@
318318

319319

320320

321-
322-
323-
---
324-
Copyright 2016 by [Mario Nebl](https://github.com/marionebl) and [contributors](./graphs/contributors). Released under the [MIT license]('./license.md').

‎docs/.nojekyll

Whitespace-only changes.

‎docs/_sidebar.md

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
* **Guides**
2+
* [Local setup](guides-local-setup.md)
3+
* [CI setup](guides-ci-setup.md)
4+
* [Use prompt](guides-use-prompt.md)
5+
* [Upgrade commitlint](guides-upgrade.md)
6+
7+
* **Concepts**
8+
* [Commit conventions](concepts-commit-conventions)
9+
* [Shareable configuration](concepts-shareable-config.md)
10+
11+
* **Reference**
12+
* [CLI](reference-cli.md)
13+
* [Rules](reference-rules.md)
14+
* [API](reference-api.md)
15+
16+
* [**Changelog**](changelog.md)

‎docs/changelog.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../changelog.md

‎docs/cli.md

-132
This file was deleted.

‎docs/concepts-commit-conventions.md

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Concept: Commit conventions
2+
3+
Commit conventions allow your team to add more semantic meaning to your git history. This e.g. includes `type`, `scope` or `breaking changes`.
4+
5+
With this additional information tools can derive useful human-readable information for releases of your project. Some examples are
6+
7+
* Automated, rich changelogs
8+
* Aumomatic version bumps
9+
* Filter fo test harnesses to run
10+
11+
The most common commit conventions follow this pattern:
12+
13+
```
14+
type(scope?): subject
15+
body?
16+
footer?
17+
```

‎docs/concepts-shareable-config.md

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Concept: Shareable configuration
2+
3+
Most commonly shareable configuration is delivered as npm package exporting
4+
an object containing `.rules` as default. To use shared configuration you specify it as item in the `.extends` array:
5+
6+
```js
7+
// commitlint.config.js
8+
module.exports = {
9+
extends: ['example'] // => @commitlint-config-example
10+
};
11+
```
12+
13+
This causes `commitlint` to pick up `commitlint-config-example`. Make it available by installing it.
14+
15+
```
16+
npm install --save-dev commitlint-config-example
17+
```
18+
19+
The rules found in `commitlint-config-example` are merged with the rules in `commitlint.config.js`, if any.
20+
21+
This works recursively, enabling shareable configuration to extend on an indefinite chain of other shareable configurations.
22+
23+
## Special cases
24+
25+
Scoped npm packages are not prefixed.
26+
27+
```js
28+
// .commitlint.config.js
29+
module.exports = {
30+
extends: ['@commitlint/config-angular'] // => @commitlint/config-angular
31+
};
32+
```
33+
34+
The same is true for relative imports
35+
36+
```js
37+
// .commitlint
38+
module.expors = {
39+
extends: ['./example'] // => ./example.js
40+
}
41+
```

‎docs/guides-ci-setup.md

+125
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Guide: CI Setup
2+
3+
Enforce commit conventions with confidence by linting on your CI servers with `commitlint`.
4+
5+
We'll use TravisCI for this guide but the principles are valid for any CI server.
6+
7+
## Install
8+
9+
```sh
10+
# Create a git repository if needed
11+
git init
12+
13+
# Create a package.json if needed
14+
npm init
15+
16+
# Install and configure if needed
17+
npm install --save-dev @commitlint-{cli,angular}
18+
echo "module.exports = {extends: ['@commitlint/config-angular']};"
19+
```
20+
21+
## First test run with Travis
22+
23+
Add a `.travis.yml` to your project root
24+
25+
```yml
26+
# .travis.yml
27+
language: node_js
28+
before_install: git fetch --unshallow
29+
script:
30+
- ./node_modules/.bin/commitlint --from=HEAD~1
31+
- npm test
32+
```
33+
34+
Make sure Travis is connected to your git repository.
35+
Trigger a build by pushing to your repository.
36+
37+
```
38+
git add .
39+
git commit -m "add travis stuff"
40+
```
41+
42+
We expect this build to fail:
43+
44+
```
45+
...
46+
./node_modules/.bin/commitlint --from=HEAD~1
47+
⧗ input: add travis stuff
48+
✖ message may not be empty [subject-empty]
49+
✖ type may not be empty [type-empty]
50+
✖ found 2 problems, 0 warnings
51+
```
52+
53+
## Linting relevant commits
54+
55+
What we did so far works but is not very useful as it simply lints the last commit in history.
56+
Let's change that by using environment information provided by TravisCI.
57+
58+
Every build exposes the commit that triggered the build via `TRAVIS_COMMIT`.
59+
60+
```yml
61+
# .travis.yml
62+
language: node_js
63+
before_install: git fetch --unshallow
64+
script:
65+
- ./node_modules/.bin/commitlint --from=$TRAVIS_COMMIT
66+
- npm test
67+
```
68+
69+
That's a bit better, but we are not handling branches at all yet. Travis provides the branch we are on via `TRAVIS_BRANCH`.
70+
71+
```yml
72+
# .travis.yml
73+
language: node_js
74+
before_install: git fetch --unshallow
75+
script:
76+
- ./node_modules/.bin/commitlint --from="$TRAVIS_BRANCH" --to="$TRAVIS_COMMIT"
77+
- ./node_modules/.bin/commitlint --from=$TRAVIS_COMMIT
78+
- npm test
79+
```
80+
81+
Nice. This handles direct commits and PR originating from the same repository. Let's add forks to the mix.
82+
83+
## The full scripts
84+
85+
We'll have to differentiate between forks and same-repo PRs on our own and move the linting to a dedicated script.
86+
87+
```yml
88+
# .travis.yml
89+
language: node_js
90+
before_install: git fetch --unshallow
91+
script:
92+
- /bin/bash lint-commits.sh"
93+
- ./node_modules/.bin/commitlint --from=$TRAVIS_COMMIT
94+
- npm test
95+
```
96+
97+
```sh
98+
# lint-commits.sh
99+
#!/bin/bash
100+
set -e
101+
set -u
102+
103+
if [[ $TRAVIS_PULL_REQUEST_SLUG != "" && $TRAVIS_PULL_REQUEST_SLUG != $TRAVIS_REPO_SLUG ]]; then
104+
# This is a Pull Request from a different slug, hence a forked repository
105+
git remote add "$TRAVIS_PULL_REQUEST_SLUG" "https://github.com/$TRAVIS_PULL_REQUEST_SLUG.git"
106+
git fetch "$TRAVIS_PULL_REQUEST_SLUG"
107+
108+
# Use the fetched remote pointing to the source clone for comparison
109+
TO="$TRAVIS_PULL_REQUEST_SLUG/$TRAVIS_PULL_REQUEST_BRANCH"
110+
else
111+
# This is a Pull Request from the same remote, no clone repository
112+
TO=$TRAVIS_COMMIT
113+
fi
114+
115+
# Lint all commits in the PR
116+
# - Covers fork pull requests (when TO=slug/branch)
117+
# - Covers branch pull requests (when TO=branch)
118+
./node_modules/.bin/commitlint --from="$TRAVIS_BRANCH" --to="$TO"
119+
120+
# Always lint the triggerig commit
121+
# - Covers direct commits
122+
./node_modules/.bin/commitlint --from="$TRAVIS_COMMIT"
123+
```
124+
125+
?> Help yourself adopting a commit convention by using an interactive commit prompt. Learn how to use `@commitlint/prompt-cli` in the [Use prompt guide](guides-use-prompt.md)

0 commit comments

Comments
 (0)