Make your first contribution¶

No permission needed. Nothing is assigned. Nobody has to reply before you start.

Pick the row that matches what you have in front of you right now.

Want to narrow it yourself instead? Filter the full list by what you have, how long you've got, and whether you want to write code.

Still undecided? Take the second row. Nobody can test YazSes on your machine but you, and that is the single most useful thing the project is missing — 297 environments are listed and almost none are covered.

The two rules¶

1. Stay inside the task's files. Each task lists what it may touch. If your change needs something else, say so in the pull request — that usually means we scoped the task wrong.
2. Remove anything personal before you push: your home path, hostname, email. yazses doctor output contains your username.

That is the whole contract. Nothing to sign — no CLA, no sign-off line, no Discord to join, no account beyond GitHub. Many tasks never need you to leave the browser.

Check your own work before you push¶

uv run python scripts/check-task.py APP-014

It runs exactly what CI will — scope, personal data, and the task's own test — against your working copy, and tells you what a human reviewer will look for. Run it and you will not be surprised by a red check on your first pull request.

Using a coding agent¶

This is welcome and normal. Claude Code, Codex, Cursor, Copilot, Gemini — all fine. Two things stay true regardless: you are the author, and you are expected to have read what it wrote. Say in the pull request that you used one; it changes how carefully we read it, never whether we accept it.

Copy this, replacing the task ID:

I'm making one contribution to the YazSes project. I remain the author and I will
read every line before it goes anywhere.

1. Read AGENTS.md and CONTRIBUTING.md in the repo root, completely.
2. Run: uv run python scripts/check-task.py <TASK-ID>
   It prints the task, the exact files I may touch, and the command that decides
   whether the work is done. Treat that output as the specification.
3. Restate the acceptance criteria back to me before changing anything.
4. Make the smallest change that satisfies the task. Do not tidy unrelated code,
   do not reformat files you did not otherwise change, do not add a dependency.
5. Never add a network call, telemetry, or a feature that is on by default —
   those are the three rules this project will not bend on.
6. Run the task's validation command and show me the real output, not a summary.
7. Show me the complete diff and explain every changed line in plain language.
8. Stop and tell me if the task needs evidence only a human can provide — that I
   actually observed something on my machine, or that a translation reads
   naturally. Do not invent either.
9. Do not commit or push until I say the diff is correct.

Point 8 matters. A compatibility report or a translation that an agent produced without a human checking it is a fabricated contribution, and it will be declined — not because AI was used, but because nobody verified it. Everything else on the list, an agent can do well.

What happens after you open the pull request¶

An automated check runs in about a minute and either says ready, or lists the exact fixes. A human replies within a few days. We would rather merge a small imperfect change and polish it afterwards than leave you waiting.

Once it lands you are added to the contributors wall, and a weekly job checks that GitHub is actually crediting you — being uncredited is the one failure people never report.

If you get stuck¶

Say so on the issue, however half-finished it is. A stuck pull request that nobody hears about is the only real failure mode here. The most common stall is uv sync on Linux, which needs a C compiler: sudo apt install build-essential python3-dev. On macOS and Windows you need nothing.