@ethima/commitlint-config 1.0.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2023 Joris Kraak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# Commitlint Configuration
+
+A shareable configuration for [Commitlint][commitlint-url] for projects
+maintained by [the Ethima organization][ethima-url]. The configuration is based
+on [the conventional commits][conventional-commits-url]
+[configuration][commitlint-config-conventional-url], with some minor
+adjustments as detailed below.
+
+## Differences from the [`config-conventional` configuration][commitlint-config-conventional-url]
+
+### More lenient rules regarding long lines in bodies and footers
+
+When referencing URIs in commit messages, which is a common scenario when
+referencing code on source hosting platforms, etc., it is trivial to trigger
+the `{body,footer}-max-line-length` rules.
+
+To ensure URIs like these can be included in commit messages, this
+configuration replaces the `{body,footer}-max-line-length` rules with the
+`{body,footer}-max-line-length-with-footnote-exemption` rules. These rules
+allow long lines in either the body or the footer of commit messages if they
+are written as Markdown footnotes, e.g. `[^1]: <long line>`,
+`[^named-footnote]: <long line>`. These footnotes can then be referenced
+elsewhere in the commit message and most hosting platforms will render these
+footnotes with proper links, etc.
+
+Both the `body-` and `footer-` rules are replaced as some URIs may trigger the
+footer detection in the commit meesage parser, particularly when a URI includes
+a `#`.
+
+### Stricter rules on merge and `fixup!`/`squash!` commits
+
+The desired workflow for projects using this configuration is to use feature
+branches that are continuously rebased on top of (pre)release branches. This
+includes the use of `fixup!` and `squash!` commits, which should all be rebased
+out _prior_ to merging into a (pre)release branch. However, by default, these
+types of commits are [allowed by the `is-ignored`
+configuration][commitlint-is-ignored-fixup-squash-url], resulting in merge/pull
+requests not being blocked when they should be by Commitlint.
+
+Additionally, [the default `is-ignored`
+configuration][commitlint-is-ignored-wildcards-url] allows different types of
+merge commits which do not align well with the process set out here, e.g.
+merging _into_ a feature branch or pulling updates using a merge strategy. All
+of these commits should also be rebased out prior to merging into a
+(pre)release branch.
+
+The only acceptable commits that are ignored by default are those related to
+"reverts", which may be used to update/undo conventionally documented changes
+prior to a release and merge commits that result from merging feature branches
+into (pre)release branches.
+
+[commitlint-config-conventional-url]: https://www.npmjs.com/package/@commitlint/config-conventional
+[commitlint-is-ignored-fixup-squash-url]: https://github.com/conventional-changelog/commitlint/blob/3bc4726f0dddfa051bc75f6af7b7ca076b04a839/%40commitlint/is-ignored/src/defaults.ts#L23
+[commitlint-is-ignored-wildcards-url]: https://github.com/conventional-changelog/commitlint/blob/3bc4726f0dddfa051bc75f6af7b7ca076b04a839/%40commitlint/is-ignored/src/defaults.ts#L17-L29
+[commitlint-url]: https://commitlint.js.org
+[conventional-commits-url]: https://conventionalcommits.org/
+[ethima-url]: https://gitlab.com/ethima/

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ethima/commitlint-config",
+  "version": "1.0.0",
+  "description": "A shareable Commitlint configuration for the Ethima organization",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "ava"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@gitlab.com/ethima/commitlint-config.git"
+  },
+  "keywords": [
+    "commitlint",
+    "ethima",
+    "configuration"
+  ],
+  "author": "Joris Kraak <me@joriskraak.nl>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://gitlab.com/ethima/commitlint-config/-/issues"
+  },
+  "homepage": "https://gitlab.com/ethima/commitlint-config",
+  "dependencies": {
+    "@commitlint/config-conventional": "18.1.0",
+    "@commitlint/is-ignored": "18.1.0"
+  },
+  "devDependencies": {
+    "@commitlint/lint": "18.1.0",
+    "@commitlint/load": "18.2.0",
+    "ava": "5.3.1"
+  }
+}

package/src/index.js

@@ -0,0 +1,72 @@
+const baseConfiguration = require("@commitlint/config-conventional");
+const {
+  wildcards: defaultIgnoreFunctions,
+} = require("@commitlint/is-ignored/lib/defaults");
+
+const footnoteMatcher = new RegExp("^\\[\\^.+?\\]:");
+
+// When referencing URIs in commit messages, it is very common to hit
+// `max-line-length` restrictions. As a work-around, these URIs may be added as
+// Markdown footnotes which can then be detected and given an exemption
+const buildMaxLineLengthWithFootnoteExemption = (section) => {
+  return (parsed, _, value) => {
+    const sectionContent = parsed[section];
+
+    if (!sectionContent) {
+      return [true];
+    }
+
+    const lines = sectionContent.split(/\r?\n/);
+
+    const result = lines.every(
+      (line) => line.length <= value || footnoteMatcher.test(line),
+    );
+
+    return [
+      result,
+      `A ${section}'s lines must not be longer than ${value} characters`,
+    ];
+  };
+};
+
+// Only keep the default ignore functions allowing:
+//
+// - Merge/pull request merge commits into (pre)release branches.
+// - Revert commits (to allow undoing/modifying previously conventionally
+//   documented changes).
+//
+// Instead of duplicating these function definitions, it is more
+// straightforward to obtain them from the defaults
+const ignores = defaultIgnoreFunctions.filter(
+  (ignoreFunction) =>
+    ignoreFunction("Revert ") || ignoreFunction("Merge 'x' into 'y' "),
+);
+
+module.exports = {
+  // Do not use the default ignore patterns as they allow patterns, e.g.
+  // `fixup!` and `squash!` commits, that should be blocked in the workflows
+  // primarily supported by this configuration
+  defaultIgnores: false,
+  extends: ["@commitlint/config-conventional"],
+  ignores,
+  plugins: [
+    {
+      rules: {
+        "body-max-line-length-with-footnote-exemption":
+          buildMaxLineLengthWithFootnoteExemption("body"),
+        "footer-max-line-length-with-footnote-exemption":
+          buildMaxLineLengthWithFootnoteExemption("footer"),
+      },
+    },
+  ],
+  // Disable the original `max-line-length` rules and replace them with
+  // versions that have an exemption for footnotes
+  rules: {
+    "body-max-line-length": [0],
+    "body-max-line-length-with-footnote-exemption":
+      baseConfiguration.rules["body-max-line-length"],
+    "footer-max-line-length": [0],
+    "footer-max-line-length-with-footnote-exemption":
+      baseConfiguration.rules["footer-max-line-length"],
+  },
+};