veryroundbird.house
1# tangled contributing guide
2
3## commit guidelines
4
5We follow a commit style similar to the Go project. Please keep commits:
6
7* **atomic**: each commit should represent one logical change
8* **descriptive**: the commit message should clearly describe what the
9change does and why it's needed
10
11### message format
12
13```
14<service/top-level directory>/<affected package/directory>: <short summary of change>
15
16
17Optional longer description can go here, if necessary. Explain what the
18change does and why, especially if not obvious. Reference relevant
19issues or PRs when applicable. These can be links for now since we don't
20auto-link issues/PRs yet.
21```
22
23Here are some examples:
24
25```
26appview/state: fix token expiry check in middleware
27
28The previous check did not account for clock drift, leading to premature
29token invalidation.
30```
31
32```
33knotserver/git/service: improve error checking in upload-pack
34```
35
36
37### general notes
38
39- PRs get merged "as-is" (fast-forward) -- like applying a patch-series
40using `git am`. At present, there is no squashing -- so please author
41your commits as they would appear on `master`, following the above
42guidelines.
43- If there is a lot of nesting, for example "appview:
44pages/templates/repo/fragments: ...", these can be truncated down to
45just "appview: repo/fragments: ...". If the change affects a lot of
46subdirectories, you may abbreviate to just the top-level names, e.g.
47"appview: ..." or "knotserver: ...".
48- Keep commits lowercased with no trailing period.
49- Use the imperative mood in the summary line (e.g., "fix bug" not
50"fixed bug" or "fixes bug").
51- Try to keep the summary line under 72 characters, but we aren't too
52fussed about this.
53- Follow the same formatting for PR titles if filled manually.
54- Don't include unrelated changes in the same commit.
55- Avoid noisy commit messages like "wip" or "final fix"—rewrite history
56before submitting if necessary.
57
58## code formatting
59
60We use a variety of tools to format our code, and multiplex them with
61[`treefmt`](https://treefmt.com): all you need to do to format your changes
62is run `nix run .#fmt` (or just `treefmt` if you're in the devshell).
63
64## proposals for bigger changes
65
66Small fixes like typos, minor bugs, or trivial refactors can be
67submitted directly as PRs.
68
69For larger changes—especially those introducing new features, significant
70refactoring, or altering system behavior—please open a proposal first. This
71helps us evaluate the scope, design, and potential impact before implementation.
72
73### proposal format
74
75Create a new issue titled:
76
77```
78proposal: <affected scope>: <summary of change>
79```
80
81In the description, explain:
82
83- What the change is
84- Why it's needed
85- How you plan to implement it (roughly)
86- Any open questions or tradeoffs
87
88We'll use the issue thread to discuss and refine the idea before moving
89forward.
90
91## developer certificate of origin (DCO)
92
93We require all contributors to certify that they have the right to
94submit the code they're contributing. To do this, we follow the
95[Developer Certificate of Origin
96(DCO)](https://developercertificate.org/).
97
98By signing your commits, you're stating that the contribution is your
99own work, or that you have the right to submit it under the project's
100license. This helps us keep things clean and legally sound.
101
102To sign your commit, just add the `-s` flag when committing:
103
104```sh
105git commit -s -m "your commit message"
106```
107
108This appends a line like:
109
110```
111Signed-off-by: Your Name <your.email@example.com>
112```
113
114We won't merge commits if they aren't signed off. If you forget, you can
115amend the last commit like this:
116
117```sh
118git commit --amend -s
119```
120
121If you're submitting a PR with multiple commits, make sure each one is
122signed.
123
124For [jj](https://jj-vcs.github.io/jj/latest/) users, you can run the following command
125to make it sign off commits in the tangled repo:
126
127```shell
128# Safety check, should say "No matching config key..."
129jj config list templates.commit_trailers
130# The command below may need to be adjusted if the command above returned something.
131jj config set --repo templates.commit_trailers "format_signed_off_by_trailer(self)"
132```
133
134Refer to the [jj
135documentation](https://jj-vcs.github.io/jj/latest/config/#commit-trailers)
136for more information.