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
36The affected package/directory can be truncated down to just the relevant dir
37should it be far too long. For example `pages/templates/repo/fragments` can
38simply be `repo/fragments`.
39
40### general notes
41
42- PRs get merged "as-is" (fast-forward) -- like applying a patch-series
43using `git am`. At present, there is no squashing -- so please author
44your commits as they would appear on `master`, following the above
45guidelines.
46- Use the imperative mood in the summary line (e.g., "fix bug" not
47"fixed bug" or "fixes bug").
48- Try to keep the summary line under 72 characters, but we aren't too
49fussed about this.
50- Don't include unrelated changes in the same commit.
51- Avoid noisy commit messages like "wip" or "final fix"—rewrite history
52before submitting if necessary.
53
54## proposals for bigger changes
55
56Small fixes like typos, minor bugs, or trivial refactors can be
57submitted directly as PRs.
58
59For larger changes—especially those introducing new features, significant
60refactoring, or altering system behavior—please open a proposal first. This
61helps us evaluate the scope, design, and potential impact before implementation.
62
63### proposal format
64
65Create a new issue titled:
66
67```
68proposal: <affected scope>: <summary of change>
69```
70
71In the description, explain:
72
73- What the change is
74- Why it's needed
75- How you plan to implement it (roughly)
76- Any open questions or tradeoffs
77
78We'll use the issue thread to discuss and refine the idea before moving
79forward.
80
81## developer certificate of origin (DCO)
82
83We require all contributors to certify that they have the right to
84submit the code they're contributing. To do this, we follow the
85[Developer Certificate of Origin
86(DCO)](https://developercertificate.org/).
87
88By signing your commits, you're stating that the contribution is your
89own work, or that you have the right to submit it under the project's
90license. This helps us keep things clean and legally sound.
91
92To sign your commit, just add the `-s` flag when committing:
93
94```sh
95git commit -s -m "your commit message"
96```
97
98This appends a line like:
99
100```
101Signed-off-by: Your Name <your.email@example.com>
102```
103
104We won't merge commits if they aren't signed off. If you forget, you can
105amend the last commit like this:
106
107```sh
108git commit --amend -s
109```
110
111If you're submitting a PR with multiple commits, make sure each one is
112signed.
113
114For [jj](https://jj-vcs.github.io/jj/latest/) users, you can add this to
115your jj config:
116
117```
118ui.should-sign-off = true
119```
120
121and to your `templates.draft_commit_description`, add the following `if`
122block:
123
124```
125 if(
126 config("ui.should-sign-off").as_boolean() && !description.contains("Signed-off-by: " ++ author.name()),
127 "\nSigned-off-by: " ++ author.name() ++ " <" ++ author.email() ++ ">",
128 ),
129```
130
131Refer to the [jj
132documentation](https://jj-vcs.github.io/jj/latest/config/#default-description)
133for more information.