style: start using conventional commits

Author: echasnovski

.github/workflows/lint.yml

@@ -37,6 +37,26 @@ jobs:
       - name: Check for changes
         run: if [[ -n $(git status -s) ]]; then exit 1; fi
 
+  gitlint:
+    name: Gitlint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v3
+        with:
+          python-version: '3.11'
+      - name: Install gitlint
+        run: pip install gitlint
+      - name: Run gitlint
+        run: |
+          if [[ -z "${GITHUB_BASE_REF}" ]]; then
+            BASE=origin/main
+          else
+            BASE="${GITHUB_BASE_REF}"
+          fi
+          echo "Linting: ${BASE}..HEAD"
+          gitlint --commits ${BASE}..HEAD
+
   case-sensitivity:
     name: File case sensitivity
     runs-on: ubuntu-latest

.gitlint

@@ -0,0 +1,14 @@
+[general]
+ignore=body-is-missing
+contrib=contrib-title-conventional-commits
+
+verbosity = 3
+
+ignore-merge-commits=true
+ignore-revert-commits=true
+ignore-fixup-commits=true
+ignore-fixup-amend-commits=true
+ignore-squash-commits=true
+
+[contrib-title-conventional-commits]
+types=ci,docs,feat,fix,refactor,revert,style,test

.pre-commit-config.yaml

@@ -11,3 +11,9 @@ repos:
         language: system
         entry: make --silent documentation
         types: []
+      - id: gitlint
+        name: Gitlint
+        language: system
+        entry: gitlint --msg-filename
+        stages: [commit-msg]
+        types: []

CONTRIBUTING.md

@@ -20,40 +20,64 @@ All well-intentioned, polite, and respectful contributions are always welcome! T
 ## Commit messages
 
 - Try to make commit message as concise as possible while giving enough information about nature of a change. Think about whether it will be easy to understand in one year time when browsing through commit history.
-- Use two part structure:
-    - First part is a change overview in present tense, preferably in single line under 80 characters. Should end with a period. Usually should be enough.
 
-      **If commit affects only one particular module (as it usually should), prepend with "(mini.\<module-name\>) ".** If commit ensures something for all modules but not necessary touches all of them, use "(all) ".
+- Single commit should change either zero or one module, or affect all modules (i.e. enforcing some universal rule but not necessarily change files). Changes for two or more modules should be split in several module-specific commits.
 
-    - Second part is optional and should contain details about the change after empty line and "Details:". Use bullet list with `-`.
+- Use [Conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) style:
+    - Messages should follow the following structure:
 
-      Use "Resolves #xxx" as separate entry if this commit resolves issue or PR.
+        ```
+        <type>[optional scope]: <description>
 
-- Use these prefixes after initial module name in described situations:
-    - "FEATURE:" - if change implements new feature (like option or function).
-    - "BREAKING:" - if change breaks current documented behavior.
-    - "BREAKING FEATURE:" - if change introduces new feature while breaking current documented behavior.
-    - "NEW MODULE:" - if change introduces new module (see 'MAINTAINING.md').
+        [optional body]
+
+        [optional footer(s)]
+        ```
+
+    - `<type>` is **mandatory** and can be one of: `ci`, `docs`, `feat`, `fix`, `refactor`, `revert`, `style`, `test`. Rule of thumb: use `docs`, `feat`, or `fix` if it is meant as change users might be interested to see; others otherwise.
+    - `[optional scope]`, if present, should be done in parenthesis `()`. If commit changes single module (as it usually should), using scope with module name is **mandatory**. If commit enforces something for all modules, use `ALL` scope.
+    - Breaking change should be expressed with `!` before `:`.
+    - `<description>` is a change overview in imperative, present tense ("change" not "changed" nor "changes"). Should result into first line under 72 characters. Should NOT end with a period.
+    - `[optional body]`, if present, should contain details and motivation about the change in plain language. Should be formatted to have maximum 80 characters in line.
+    - `[optional footer(s)]`, if present, should be instructions to Git or Github. Use "Resolves #xxx" as separate entry if this commit resolves issue or PR.
 
 - Use module's function and field names without module's name. Like `add()` and not `MiniSurround.add()`.
 
 Examples:
 
 ```
-Fix typo in 'README.md'.
+feat(deps): add folds in update confirmation buffer
+```
+
+```
+fix(jump): make operator not delete one character if target is not found
+
+One main goal is to do that in a dot-repeatable way, because this is very
+likely to be repeated after an unfortunate first try.
+
+Resolves #688
+```
+
 ```
+refactor(bracketed): update `treesitter()` to not source 'vim.treesitter' on `require()`
 
+Although less explicit, this considerably reduces startup footprint of
+'mini.bracketed' in isolation.
 ```
-(mini.animate) Update `cursor` to use virtual columns.
 
-Details:
-- Resolves #258.
+```
+feat(hues)!: update verbatim text to be distinctive
 ```
 
 ```
-(mini.comment) FEATURE: add `options.pad_comment_leaders` option.
+test(ALL): update screenshots to work on Nightly
 ```
 
+### Automation
+
+- [Install `gitlint`](https://jorisroovers.com/gitlint/latest/installation/).
+- Lint manually with `gitlint` after the commit or better yet [install pre-commit](https://pre-commit.com/#install) and enable it with `pre-commit install` (from the root directory). This will auto-lint commit message before finalizing it.
+
 ## Generating help file
 
 If your contribution updates annotations used to generate help file, please regenerate it. You can make this with one of the following (assuming current directory being project root):
@@ -76,7 +100,7 @@ If you have Windows or MacOS and want to contribute code related change, make yo
 
 This project uses [StyLua](https://github.com/JohnnyMorganz/StyLua) version 0.14.0 for formatting Lua code. Before making changes to code, please:
 
-- [Install StyLua](https://github.com/JohnnyMorganz/StyLua#installation). NOTE: use `v0.14.0`.
+- [Install StyLua](https://github.com/JohnnyMorganz/StyLua#installation). NOTE: use `v0.19.0`.
 - Format with it. Currently there are two ways to do this:
     - Manually run `stylua .` from the root directory of this project.
     - [Install pre-commit](https://pre-commit.com/#install) and enable it with `pre-commit install` (from the root directory). This will auto-format relevant code before making commits.

MAINTAINING.md

@@ -56,7 +56,7 @@ Usual workflow involves performing these steps after every commit in 'mini.nvim'
 - Update main README to mention new module in table of contents.
 - Update 'CHANGELOG.md' to mention introduction of new module.
 - Update 'CONTRIBUTING.md' to mention new highlight groups (if there are any).
-- Commit changes with message '(mini.xxx) NEW MODULE: initial commit.'. NOTE: it is cleaner to synchronize standalone repositories prior to this commit.
+- Commit changes with message 'feat(xxx): add NEW MODULE'. NOTE: it is cleaner to synchronize standalone repositories prior to this commit.
 - If there are new highlight groups, follow up with adding explicit support in color scheme modules.
 - Make standalone plugin:
     - Create new empty GitHub repository. Disable Issues and limit PRs.