yoten.app / yoten
Yōten: A social tracker for your language learning journey built on the atproto.
fork atom
yoten / docs / contributing.md
at master 3.6 kB view raw view code

Contributing guide#

Commit guidelines#

We follow a commit style similar to the Go project. Please keep commits:

  • Atomic: Each commit should represent one logical change.
  • Descriptive: The commit message should clearly describe what the change does and why it's needed.

Message format#

<type>(affected system): <short summary of change>


Optional longer description, if necessary. Explain what the change does and
why. Reference relevant issues or PRs when applicable via links.

Examples

fix(xp): update xp when a study session is deleted

refactor(views/edit-activity): remove page handler in favor of direct invocation

General notes#

  • PRs get merged "as-is" (fast-forward) - like applying a patch-series using git am. There is no squashing so please author your commits as they would appear on master, following the above guidelines.
  • Keep commits lowercased with no trailing period.
  • Use the imperative mood in the summary line (e.g., "fix bug" not "fixed bug" or "fixes bug").
  • Try to keep the summary line under 72 characters.
  • Follow the same formatting for PR titles if filled manually.
  • Don't include unrelated changes in the same commit.
  • Avoid noisy commit messages like "wip" or "final fix". Rewrite history before submitting if necessary.

Code formatting#

Format templates and code before submitting for final review.

go tool templ fmt ./internal/server/views/ && go fmt ./...

Proposals for bigger changes#

Small fixes like typos, minor bugs, or trivial refactors can be submitted directly as PRs.

For larger changes—especially those introducing new features, significant refactoring, or altering system behavior—please open a proposal first. This helps us evaluate the scope, design, and potential impact before implementation.

Proposal format#

Create a new issue titled:

proposal: <affected scope>: <summary of change>

In the description, explain:

  • What the change is
  • Why it's needed
  • How you plan to implement it (roughly)
  • Any open questions or tradeoffs

We'll use the issue thread to discuss and refine the idea before moving forward.

Developer certificate of origin (DCO)#

We require all contributors to certify that they have the right to submit the code they're contributing. To do this, we follow the Developer Certificate of Origin (DCO).

By signing your commits, you're stating that the contribution is your own work, or that you have the right to submit it under the project's license. This helps us keep things clean and legally sound.

To sign your commit, just add the -s flag when committing:

git commit -s -m "your commit message"

This appends a line like:

Signed-off-by: Your Name <your.email@example.com>

We won't merge commits if they aren't signed off. If you forget, you can amend the last commit like this:

git commit --amend -s

If you're submitting a PR with multiple commits, make sure each one is signed.

Commit Authoring#

To ensure a consistent and clean project history, we use a .mailmap file to consolidate contributions from different email addresses.

If you have committed to this project with multiple emails in the past, or plan to in the future, please add an entry to the .mailmap file in the root of the repository. This will ensure all your work is correctly attributed to a single identity.

The format is: Preferred Name <preferred@email.com> <old@email.com>

Please include this change in your first pull request.