Contributing Guidelines

Who this is for

Anyone submitting code, documentation, watchfaces, translations, or other contributions to any AsteroidOS repository, whether you are a first-time contributor or a regular one.

Before you start

Read the contributors agreement.

It is short and covers licensing, copyright, and the project's independence from commercial interests. If you are unsure whether your contribution fits the project or how to approach a problem technically, ask first. The IRC channel and Matrix room are the right place. Nobody has ever been turned away for asking a basic question early. Asking late, after submitting something that needs significant rework, costs everyone more time.

Patience and mutual respect

Everyone involved in AsteroidOS — contributors and maintainers alike — is giving their free time. There are zero expectations on review or development timelines in either direction. Do not pressure maintainers for reviews, and do not pressure contributors for updates. Life happens, things take as long as they take, and that is completely fine. If a PR sits without movement for a while, a single polite ping after a reasonable wait is always welcome. Repeated pressure is not.

Submitting a pull request

One concern per PR. If you are fixing a bug and also cleaning up whitespace, those are two separate commits at minimum and potentially two PRs. Reviewers should be able to understand and approve each change independently.

Write commit messages that explain why, not just what. "Fix timer reset" is less useful than "Reset timer on visibility change to prevent stale state on re-entry". The diff shows what changed; the message should explain the reasoning.

AsteroidOS uses a two-eyes principle: every merge requires review by at least one maintainer who did not author the change. If your PR is a work in progress, mark it as a draft. Do not ask for review on unfinished code. Reference any related issue in the PR description.

Using AI and LLM tools

AsteroidOS welcomes contributors who use AI coding assistants. We ask for transparency so reviewers can give useful feedback.

State in your PR description that you used an LLM tool and name it (e.g. "drafted with Claude" or "written with Copilot"). Include or link the context and key prompts you used, a gist is fine. This helps reviewers identify systematic pattern issues and improve the project's own LLM context resources rather than leaving the same feedback repeatedly.

Explain how you validated the output. At minimum this means you reviewed the code and design yourself and tested it by building and running it on a device or emulator. Submitting LLM output that has not been built, run, or reasoned about independently damages trust in the same way that submitting any other untested or unjustified change does. You are responsible for what you submit.

Do not paste LLM-generated text into Matrix or GitHub discussions. Write in your own words. Reviewers notice, and it damages trust in ways that are hard to recover from. If you are uncertain whether your understanding is correct, say so. "I think this is right but I'm not sure" is always a better opening than presenting guesswork as fact.

If your PR is rejected or needs changes

Rejection is feedback, not judgement. If a reviewer asks for changes or closes a PR, they will explain why. If the explanation is unclear, ask for clarification in the PR thread. If you disagree with a review decision, say so in the thread with your reasoning. Maintainers are not infallible and have changed their minds before.