summaryrefslogtreecommitdiffstats
path: root/docs/contrib_rules.md
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2020-03-19 14:00:14 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2020-03-19 14:00:14 +0000
commitdf9615bac55ac6f1c3f516b66279ac0007175030 (patch)
tree84dd81d1c97835271cea7fbdd67c074742365e07 /docs/contrib_rules.md
parentInitial commit. (diff)
downloadgitlint-df9615bac55ac6f1c3f516b66279ac0007175030.tar.xz
gitlint-df9615bac55ac6f1c3f516b66279ac0007175030.zip
Adding upstream version 0.13.1.upstream/0.13.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r--docs/contrib_rules.md67
1 files changed, 67 insertions, 0 deletions
diff --git a/docs/contrib_rules.md b/docs/contrib_rules.md
new file mode 100644
index 0000000..a4f4f0d
--- /dev/null
+++ b/docs/contrib_rules.md
@@ -0,0 +1,67 @@
+# Using Contrib Rules
+_Introduced in gitlint v0.12.0_
+
+Contrib rules are community-**contrib**uted rules that are disabled by default, but can be enabled through configuration.
+
+Contrib rules are meant to augment default gitlint behavior by providing users with rules for common use-cases without
+forcing these rules on all gitlint users. This also means that users don't have to
+re-implement these commonly used rules themselves as [user-defined](user_defined_rules) rules.
+
+To enable certain contrib rules, you can use the ```--contrib``` flag.
+```sh
+$ cat examples/commit-message-1 | gitlint --contrib contrib-title-conventional-commits,CC1
+1: CC1 Body does not contain a 'Signed-Off-By' line
+1: CL1 Title does not start with one of fix, feat, chore, docs, style, refactor, perf, test: "WIP: This is the title of a commit message."
+
+# These are the default violations
+1: T3 Title has trailing punctuation (.): "WIP: This is the title of a commit message."
+1: T5 Title contains the word 'WIP' (case-insensitive): "WIP: This is the title of a commit message."
+2: B4 Second line is not empty: "The second line should typically be empty"
+3: B1 Line exceeds max length (123>80): "Lines typically need to have a max length, meaning that they can't exceed a preset number of characters, usually 80 or 120."
+```
+
+Same thing using a ```.gitlint``` file:
+
+```ini
+[general]
+# You HAVE to add the rule here to enable it, only configuring (such as below)
+# does NOT enable it.
+contrib=contrib-title-conventional-commits,CC1
+
+
+[contrib-title-conventional-commits]
+# Specify allowed commit types. For details see: https://www.conventionalcommits.org/
+types = bugfix,user-story,epic
+```
+
+You can also configure contrib rules using [any of the other ways to configure gitlint](configuration.md).
+
+# Available Contrib Rules
+
+ID | Name | gitlint version | Description
+------|-------------------------------------|------------------ |-------------------------------------------
+CT1 | contrib-title-conventional-commits | >= 0.12.0 | Enforces [Conventional Commits](https://www.conventionalcommits.org/) commit message style on the title.
+CC1 | contrib-requires-signed-off-by | >= 0.12.0 | Commit body must contain a `Signed-Off-By` line.
+
+## CT1: contrib-title-conventional-commits ##
+
+ID | Name | gitlint version | Description
+------|---------------------------------------|--------------------|-------------------------------------------
+CT1 | contrib-title-conventional-commits | >= 0.12.0 | Enforces [Conventional Commits](https://www.conventionalcommits.org/) commit message style on the title.
+
+### Options ###
+
+Name | gitlint version | Default | Description
+---------------|--------------------|--------------|----------------------------------
+types | >= 0.12.0 | `fix,feat,chore,docs,style,refactor,perf,test,revert` | Comma separated list of allowed commit types.
+
+
+## CC1: contrib-requires-signed-off-by ##
+
+ID | Name | gitlint version | Description
+------|---------------------------------------|--------------------|-------------------------------------------
+CC1 | contrib-requires-signed-off-by | >= 0.12.0 | Commit body must contain a `Signed-Off-By` line. This means, a line that starts with the `Signed-Off-By` keyword.
+
+
+# Contributing Contrib rules
+We'd love for you to contribute new Contrib rules to gitlint or improve existing ones! Please visit the [Contributing](contributing) page on how to get started. \ No newline at end of file