diff options
| -rw-r--r-- | .gitlint | 138 | ||||
| -rw-r--r-- | .pre-commit-config.yaml | 7 | ||||
| -rw-r--r-- | docs/docs/development/contributing/commit-messages.md | 70 | ||||
| -rw-r--r-- | docs/docs/development/local-toolchain/pre-commit.md | 4 | ||||
| -rw-r--r-- | docs/sidebars.js | 1 |
5 files changed, 218 insertions, 2 deletions
diff --git a/.gitlint b/.gitlint new file mode 100644 index 0000000000..f5ed1479da --- /dev/null +++ b/.gitlint @@ -0,0 +1,138 @@ +# Edit this file as you like. +# +# All these sections are optional. Each section with the exception of [general] represents +# one rule and each key in it is an option for that specific rule. +# +# Rules and sections can be referenced by their full name or by id. For example +# section "[body-max-line-length]" could also be written as "[B1]". Full section names are +# used in here for clarity. +# +[general] +# Ignore certain rules, this example uses both full name and id +# ignore=title-trailing-punctuation, T3 + +# verbosity should be a value between 1 and 3, the commandline -v flags take precedence over this +# verbosity = 2 + +# By default gitlint will ignore merge, revert, fixup, fixup=amend, and squash commits. +# ignore-merge-commits=true +# ignore-revert-commits=true +# ignore-fixup-commits=true +# ignore-fixup-amend-commits=true +# ignore-squash-commits=true + +# Ignore any data sent to gitlint via stdin +# ignore-stdin=true + +# Fetch additional meta-data from the local repository when manually passing a +# commit message to gitlint via stdin or --commit-msg. Disabled by default. +# staged=true + +# Hard fail when the target commit range is empty. Note that gitlint will +# already fail by default on invalid commit ranges. This option is specifically +# to tell gitlint to fail on *valid but empty* commit ranges. +# Disabled by default. +# fail-without-commits=true + +# Whether to use Python `search` instead of `match` semantics in rules that use +# regexes. Context: https://github.com/jorisroovers/gitlint/issues/254 +# Disabled by default, but will be enabled by default in the future. +# regex-style-search=true + +# Enable debug mode (prints more output). Disabled by default. +# debug=true + +# Enable community contributed rules +# See http://jorisroovers.github.io/gitlint/contrib_rules for details +contrib=contrib-title-conventional-commits,CT1,contrib-disallow-cleanup-commits,CC2 + +# Set the extra-path where gitlint will search for user defined rules +# See http://jorisroovers.github.io/gitlint/user_defined_rules for details +# extra-path=examples/ + +[title-max-length] +line-length=80 + +# Conversely, you can also enforce minimal length of a title with the +# "title-min-length" rule: +# [title-min-length] +# min-length=5 + +# [title-must-not-contain-word] +# Comma-separated list of words that should not occur in the title. Matching is case +# insensitive. It's fine if the keyword occurs as part of a larger word (so "WIPING" +# will not cause a violation, but "WIP: my title" will. +# words=wip + +# [title-match-regex] +# python-style regex that the commit-msg title must match +# Note that the regex can contradict with other rules if not used correctly +# (e.g. title-must-not-contain-word). +# regex=^US[0-9]* + +# [body-max-line-length] +# line-length=72 + +# [body-min-length] +# min-length=5 + +# [body-is-missing] +# Whether to ignore this rule on merge commits (which typically only have a title) +# default = True +# ignore-merge-commits=false + +# [body-changed-file-mention] +# List of files that need to be explicitly mentioned in the body when they are changed +# This is useful for when developers often erroneously edit certain files or git submodules. +# By specifying this rule, developers can only change the file when they explicitly reference +# it in the commit message. +# files=gitlint-core/gitlint/rules.py,README.md + +# [body-match-regex] +# python-style regex that the commit-msg body must match. +# E.g. body must end in My-Commit-Tag: foo +# regex=My-Commit-Tag: foo$ + +# [author-valid-email] +# python-style regex that the commit author email address must match. +# For example, use the following regex if you only want to allow email addresses from foo.com +# regex=[^@][email protected] + +# [ignore-by-title] +# Ignore certain rules for commits of which the title matches a regex +# E.g. Match commit titles that start with "Release" +# regex=^Release(.*) + +# Ignore certain rules, you can reference them by their id or by their full name +# Use 'all' to ignore all rules +# ignore=T1,body-min-length + +# [ignore-by-body] +# Ignore certain rules for commits of which the body has a line that matches a regex +# E.g. Match bodies that have a line that that contain "release" +# regex=(.*)release(.*) +# +# Ignore certain rules, you can reference them by their id or by their full name +# Use 'all' to ignore all rules +# ignore=T1,body-min-length + +# [ignore-body-lines] +# Ignore certain lines in a commit body that match a regex. +# E.g. Ignore all lines that start with 'Co-Authored-By' +# regex=^Co-Authored-By + +# [ignore-by-author-name] +# Ignore certain rules for commits of which the author name matches a regex +# E.g. Match commits made by dependabot +# regex=(.*)dependabot(.*) +# +# Ignore certain rules, you can reference them by their id or by their full name +# Use 'all' to ignore all rules +# ignore=T1,body-min-length + +# This is a contrib rule - a community contributed rule. These are disabled by default. +# You need to explicitly enable them one-by-one by adding them to the "contrib" option +# under [general] section above. +# [contrib-title-conventional-commits] +# Specify allowed commit types. For details see: https://www.conventionalcommits.org/ +# types = bugfix,user-story,epic diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 352ad72327..1c6d560cef 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -4,7 +4,7 @@ repos: rev: v1.5.1 hooks: - id: remove-tabs - exclude: "vendor-prefixes\\.txt$" + exclude: "vendor-prefixes\\.txt$|.git/COMMIT_EDITMSG" - repo: https://github.com/pre-commit/mirrors-clang-format rev: v18.1.8 hooks: @@ -16,9 +16,14 @@ repos: rev: v2.7.1 hooks: - id: prettier + exclude: ".git/COMMIT_EDITMSG" # Workaround for https://github.com/pre-commit/mirrors-prettier/issues/29 additional_dependencies: + - repo: https://github.com/jorisroovers/gitlint + rev: v0.19.1 + hooks: + - id: gitlint - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.4.0 hooks: diff --git a/docs/docs/development/contributing/commit-messages.md b/docs/docs/development/contributing/commit-messages.md new file mode 100644 index 0000000000..241d118dff --- /dev/null +++ b/docs/docs/development/contributing/commit-messages.md @@ -0,0 +1,70 @@ +--- +title: Commit Messages +--- + +The ZMK project uses [conventional commits](https://www.conventionalcommits.org/) for their commit messages. This not only provides consistency for our commits, but also allows for release/versioning automation to determine the next version to release, generating changelogs, etc. + +Commit messages will be checked as part of our CI process by GitHub Actions. + +## Guidelines + +Commits should have the following: + +- A first line prefix that includes a [type](#types), as well as appropriate [scope](#scopes) in parentheses as needed. +- Following the prefix, a concise summary of the change, which documents the new behavior/feature/functionality in the positive (e.g. "wake from sleep now works with charlieplex kscan", not "fixed waked from sleep bug with charlieplex kscan driver"). +- A blank line following the first line. +- A body that provides more detail of the changes. This _may_ be a bulleted list or paragraph prose. +- An optional set of [git trailers](https://git-scm.com/docs/git-interpret-trailers#_description) for things like [GitHub keywords](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests) following a blank line. + +## Example + +Here is an example of a good commit message: + +``` +feat(boards): Add numpad layouts + +Added physical layouts for the following variants of numpads: + +- With and without extra top row +- 2U plus key or 1U plus and backspace keys +- 2U 0 key or 1U 0 and 00 keys +- Full 1U grid/macropad layout + +Other layouts exist, such as "southpaw" horizontally mirrored layouts, +and layouts with a fifth column, but those seem to be much less common. +``` + +## Pre-Commit + +To help make sure you don't need to wait for GitHub Actions to check your commits, you can [set up pre-commit](../local-toolchain/pre-commit.md) to check your commits as you create them. + +## Types + +The following commit types are used by ZMK: + +- `blog:` -- changes to our documentation found in the `docs/blog` directory +- `docs:` -- changes to our documentation found in the `docs/` directory, except blogs +- `feat:` -- changes that add a new feature +- `fix:` -- changes that fix existing functionality +- `refactor:` -- changes that refactor existing functionality without adding any new features +- `feat!:`/`refactor!:`/`fix!:` -- same as above, but indicates a breaking change. Examples would be changes to the public C API, renaming a board/shield, editing a board or shield to rename devicetree labels that may be used in keymaps, etc. +- `ci:` -- changes to our continuous integration setup with GitHub Actions, usually only for the files in `.github/workflows/` +- `chore:` -- grab bag type for small changes that don't fall into any of the above categories, including dependency updates for development tools and docs. + +## Scopes + +The following scopes are frequently used to further clarify the scope of the change: + +- `hid` -- changes to our general HID code +- `usb` -- changes specific to USB +- `ble` -- changes specific to BLE +- `power` -- changes to our power management code +- `split` -- changes to our split keyboard support +- `studio` -- changes to our ZMK Studio code +- `display` -- changes to to our display code +- `underglow` -- changes to to our RGB underglow support +- `backlight` -- changes to to our simple LED backlight support +- `behaviors` -- changes to to our core behavior code +- `core` -- changes to any other area of our core code +- `boards` -- changes to the in-tree boards +- `shields` -- changes to the in-tree shields diff --git a/docs/docs/development/local-toolchain/pre-commit.md b/docs/docs/development/local-toolchain/pre-commit.md index b4306fc952..fdc66513fd 100644 --- a/docs/docs/development/local-toolchain/pre-commit.md +++ b/docs/docs/development/local-toolchain/pre-commit.md @@ -22,12 +22,14 @@ Now that pre-commit is installed on your PC, you need to install it into the ZMK ```bash pre-commit install +pre-commit install --hook-type commit-msg ``` This should print a message such as ``` -pre-commit installed at .git\hooks\pre-commit +pre-commit installed at .git/hooks/pre-commit +pre-commit installed at .git/hooks/commit-msg ``` Pre-commit will now automatically check your changes whenever you run `git commit`. If it detects a problem, it will describe the problem and cancel the commit. For simple problems such as incorrect formatting, it will also automatically fix the files so you can just `git add` them and try again. diff --git a/docs/sidebars.js b/docs/sidebars.js index 6452130acc..3cdd84e638 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -142,6 +142,7 @@ module.exports = { collapsed: true, items: [ "development/contributing/clean-room", + "development/contributing/commit-messages", "development/contributing/documentation", ], }, |