notnite.com
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>: <package/path>: <short summary of change>
15
16
17Optional longer description, if needed. Explain what the change does and
18why, especially if not obvious. Reference relevant issues or PRs when
19applicable. These can be links for now since we don't auto-link
20issues/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 a single commit, so keep PRs small and focused. Use
39the above guidelines for the PR title and description.
40- Use the imperative mood in the summary line (e.g., "fix bug" not
41"fixed bug" or "fixes bug").
42- Try to keep the summary line under 72 characters, but we aren't too
43fussed about this.
44- Don't include unrelated changes in the same commit.
45- Avoid noisy commit messages like "wip" or "final fix"—rewrite history
46before submitting if necessary.
47
48## proposals for bigger changes
49
50Small fixes like typos, minor bugs, or trivial refactors can be
51submitted directly as PRs.
52
53For larger changes—especially those introducing new features,
54significant refactoring, or altering system behavior—please open a
55proposal first. This helps us evaluate the scope, design, and potential
56impact before implementation.
57
58### proposal format
59
60Create a new issue titled:
61
62```
63proposal: <affected scope>: <summary of change>
64```
65
66In the description, explain:
67
68- What the change is
69- Why it's needed
70- How you plan to implement it (roughly)
71- Any open questions or tradeoffs
72
73We'll use the issue thread to discuss and refine the idea before moving
74forward.