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### general notes
37
38- PRs get merged "as-is" (fast-forward) -- like applying a patch-series
39using `git am`. At present, there is no squashing -- so please author
40your commits as they would appear on `master`, following the above
41guidelines.
42- Use the imperative mood in the summary line (e.g., "fix bug" not
43"fixed bug" or "fixes bug").
44- Try to keep the summary line under 72 characters, but we aren't too
45fussed about this.
46- Don't include unrelated changes in the same commit.
47- Avoid noisy commit messages like "wip" or "final fix"—rewrite history
48before submitting if necessary.
49
50## proposals for bigger changes
51
52Small fixes like typos, minor bugs, or trivial refactors can be
53submitted directly as PRs.
54
55For larger changes—especially those introducing new features,
56significant refactoring, or altering system behavior—please open a
57proposal first. This helps us evaluate the scope, design, and potential
58impact before implementation.
59
60### proposal format
61
62Create a new issue titled:
63
64```
65proposal: <affected scope>: <summary of change>
66```
67
68In the description, explain:
69
70- What the change is
71- Why it's needed
72- How you plan to implement it (roughly)
73- Any open questions or tradeoffs
74
75We'll use the issue thread to discuss and refine the idea before moving
76forward.