yoten.app
Yōten: A social tracker for your language learning journey built on the atproto.
brookjeynes.dev
1# 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 change
9 does and why it's needed.
10
11### Message format
12
13```
14<type>(affected system): <short summary of change>
15
16
17Optional longer description, if necessary. Explain what the change does and
18why. Reference relevant issues or PRs when applicable via links.
19```
20
21Examples
22
23```
24fix(xp): update xp when a study session is deleted
25```
26
27```
28refactor(views/edit-activity): remove page handler in favor of direct invocation
29```
30
31### General notes
32
33- PRs get merged "as-is" (fast-forward) - like applying a patch-series using
34 `git am`. There is no squashing so please author your commits as they would
35 appear on `master`, following the above guidelines.
36- Keep commits lowercased with no trailing period.
37- Use the imperative mood in the summary line (e.g., "fix bug" not "fixed bug"
38 or "fixes bug").
39- Try to keep the summary line under 72 characters.
40- Follow the same formatting for PR titles if filled manually.
41- Don't include unrelated changes in the same commit.
42- Avoid noisy commit messages like "wip" or "final fix". Rewrite history before
43 submitting if necessary.
44
45## Code formatting
46
47Format templates and code before submitting for final review.
48```
49go tool templ fmt ./internal/server/views/ && go fmt ./...
50```
51
52## Proposals for bigger changes
53
54Small fixes like typos, minor bugs, or trivial refactors can be submitted
55directly as PRs.
56
57For larger changes—especially those introducing new features, significant
58refactoring, or altering system behavior—please open a proposal first. This
59helps us evaluate the scope, design, and potential impact before
60implementation.
61
62### Proposal format
63
64Create a new issue titled:
65
66```
67proposal: <affected scope>: <summary of change>
68```
69
70In the description, explain:
71
72- What the change is
73- Why it's needed
74- How you plan to implement it (roughly)
75- Any open questions or tradeoffs
76
77We'll use the issue thread to discuss and refine the idea before moving
78forward.
79
80## Developer certificate of origin (DCO)
81
82We require all contributors to certify that they have the right to submit the
83code they're contributing. To do this, we follow the [Developer Certificate of
84Origin (DCO)](https://developercertificate.org/).
85
86By signing your commits, you're stating that the contribution is your own work,
87or that you have the right to submit it under the project's license. This helps
88us keep things clean and legally sound.
89
90To sign your commit, just add the `-s` flag when committing:
91
92```sh
93git commit -s -m "your commit message"
94```
95
96This appends a line like:
97
98```
99Signed-off-by: Your Name <your.email@example.com>
100```
101
102We won't merge commits if they aren't signed off. If you forget, you can amend
103the last commit like this:
104
105```sh
106git commit --amend -s
107```
108
109If you're submitting a PR with multiple commits, make sure each one is signed.
110
111## Commit Authoring
112
113To ensure a consistent and clean project history, we use a `.mailmap` file to
114consolidate contributions from different email addresses.
115
116If you have committed to this project with multiple emails in the past, or plan
117to in the future, please add an entry to the `.mailmap` file in the root of the
118repository. This will ensure all your work is correctly attributed to a single
119identity.
120
121The format is: `Preferred Name <preferred@email.com> <old@email.com>`
122
123Please include this change in your first pull request.