alice.pds.demo.boltless.dev
This repository has no description
2.7 kB
72 lines
1# Contributing
2
3## Commit messages
4
5We follow the [Go commit message convention][go] (the same style [Tailscale][ts]
6uses). The subject line is:
7
8```
9pkg/path: short summary in the imperative mood
10```
11
12- **Prefix**: the package or path affected, from the repo root. Use a real Go
13 package (`appview/pages`, `knot2/xrpc`) or the actual top-level path — e.g.
14 `.tangled/workflows:`, **not** `workflows:`. If several packages are touched,
15 either abbreviate to top-level names (`api,lexicons:`) or group subpackages
16 with braces (`appview/{config,state}:`). Do **not** use Conventional Commit
17 types (`feat:`, `fix:`, `chore:`); name the package instead.
18- **Summary**: a lowercase, imperative-mood verb phrase — "add", not "added" /
19 "adds" / "adding". No trailing period. Keep it under ~76 characters.
20- Leave a blank line between the summary and the body.
21- Use the body to explain *what* changed and *why*, wrapped at ~76 columns.
22
23### Examples
24
25```
26ogre: pluralize metrics # good
27knot2/xrpc: forward X-Forwarded-For headers # good
28api,lexicons: add lexicons for private xrpc # good
29appview/{config,state}: gate xrpc router # good
30
31fix: pluralize metrics in ogre # bad — Conventional Commit prefix
32workflows/rust: run checks and tests # bad — no top-level `workflows/`; use `.tangled/workflows`
33bobbin extra certs # bad — no package prefix
34web: Added reactions # bad — capitalized, past tense
35```
36
37Reference: <https://go.dev/wiki/CommitMessage>.
38
39## Enforcement
40
41Commit messages are linted by [`.tangled/hooks/commit-msg-lint.sh`](.tangled/hooks/commit-msg-lint.sh),
42which runs both in CI and, optionally, as a local git hook.
43
44### CI
45
46The [`commit-lint`](.tangled/workflows/commit-lint.yml) workflow runs on every
47push and pull request to `master`. On a pull request it lints every commit
48between the target branch and the PR head; on a push it lints the pushed commit.
49
50### Local git hook
51
52Install the repo's git hooks once, so bad messages are caught before you commit:
53
54```sh
55./.tangled/hooks/install.sh
56```
57
58This points `core.hooksPath` at `.tangled/hooks`. Bypass the check for a single
59commit with `git commit --no-verify`. To undo: `git config --unset core.hooksPath`.
60
61### jj (jujutsu)
62
63`jj` does not run git hooks, so `jj` users rely on the CI check. You can lint a
64change locally at any time:
65
66```sh
67.tangled/hooks/commit-msg-lint.sh --rev @ # lint the current change
68.tangled/hooks/commit-msg-lint.sh --range main @ # lint a range
69```
70
71[go]: https://go.dev/wiki/CommitMessage
72[ts]: https://github.com/tailscale/tailscale/blob/main/docs/commit-messages.md