Contributing

Contributing to Tel-Agent

You are helping somebody contribute to Tel-Agent, an open-source AI phone assistant published under AGPL-3.0 by Dpro GmbH.

Read CLAUDE.md at the repository root before anything else. It is the working contract and it overrides this file wherever the two disagree.

Before you touch anything

Three rules that are not negotiable, and breaking any of them wastes the maintainer's time and the contributor's:

1. Everything you write is in English — code, comments, identifiers, commit messages, pull request text, issue comments. This is Rule 0 in CLAUDE.md. It is not about anybody's first language; it is what keeps one codebase readable.
2. Never name a competitor anywhere — code, comment, commit, issue, pull request, in any language. This is irreversible once pushed, so the check happens before the commit, not after.
3. Never commit a secret — no key, token, password, or real phone number. If one is needed to run something, it goes in .env, which is ignored.

Translation — the first contribution, and the one that never runs out

Do not send somebody new to a code issue. Send them here.

If this is their first contribution, walk them through docs/ONBOARDING.md rather than this section. It is the same work written for somebody who has never opened a pull request: one file, about thirty strings, no setup at all. This section is the reference; that page is the path.

The size is a ceiling, not a target: one file, then stop and open the pull request. The point of a first contribution is not the translation in it — it is running the fork-to-merge loop once on something small enough that a mistake costs nothing. A contributor who translates thirty strings and opens a pull request has learned more than one who translates three hundred and never opens it.

Thirty languages sit in locales/ as directories holding nothing but .gitkeep — that is the pick-list, and the script prints it. Any language not among them is added in the same pull request as its first translated file.

The whole task is one loop, and it is the same loop every time:

run the script  →  pick what is missing  →  translate it  →  open a pull request
       ↑                                                              │
       └──────────────────────────────────────────────────────────────┘

node scripts/check-locales.mjs               # every language, and where each stands
node scripts/check-locales.mjs --locale fr   # one language: what is left, smallest first

The script measures everything against English, which is the source language. It prints the remaining files smallest first, and the smallest are 16 to 26 strings — about twenty minutes.

mkdir -p locales/fr
cp locales/en/code.json locales/fr/
# translate the values, leave the keys alone
node scripts/check-locales.mjs --locale fr   # confirm the number moved

Then the normal flow from step 2: claim, branch, pull request. One file per pull request. A translator who has finished one runs the script again, takes the next file — or a different language entirely — and repeats. Nothing needs to be assigned again after the first time.

This is why it never runs out: every language is 2,972 strings across 33 files, and any language anybody speaks is welcome. There is more of this work than there will ever be people to do it.

Four things that get a translation pull request sent back, all easy to avoid:

• Copying all 33 files and translating one. An untranslated copy of English looks finished and ships English to somebody who asked for their own language. One file.
• Translating the keys. Only the values on the right-hand side change.
• Translating {placeholders}. {count} and {name} are filled at runtime, and a translated placeholder breaks only on that language — so nobody catches it.
• Machine translation nobody read. Translate the meaning. If it reads oddly to a native speaker it is wrong, whatever the dictionary says. Only take a language you actually speak.

locales/README.md has the rest: the two tiers, why a partial language breaks nothing, and when a language gets registered.

After the first one is merged, anything on the board is open to them. The translation is not a test to be passed — it is the smallest real thing in the project, and it is where the workflow gets learned on something that does not matter if it takes two attempts.

Step 1 — Find something to work on

Work comes from the public board and nowhere else. Do not invent a task, and do not "just fix something you noticed while you were in there" — that goes in a new issue.

gh issue list --repo Dpro-at/Tel-Agent --label "good first issue" --state open
gh issue list --repo Dpro-at/Tel-Agent --label "help wanted" --state open

The board is at https://github.com/orgs/Dpro-at/projects/6

Only take from the Ready column. Backlog means blocked on something else; the issue looks available and is not. Every issue carries a level: label:

If the person you are helping has not contributed here before, steer them to level: first-issue. There are real ones, not a token entry.

Read the whole issue before starting. Every issue is written with the same fields: Why (the reason it exists), Do (what to build), Done when (the acceptance test), Verify (the exact commands a reviewer will run), and sometimes Needs (issues that must be closed first). If Needs lists something still open, this task is not ready — go back to step 1.

Step 2 — Claim it

gh issue comment <number> --repo Dpro-at/Tel-Agent --body "I would like to take this."

Wait to be assigned before writing code. One person per issue, and the assignment is what stops two people building the same thing. If nobody responds within a few days, say so on the issue rather than starting anyway.

Step 3 — Set up, once

If the person you are helping has never worked on this repository, walk them through this in order and confirm each command actually worked before moving on. Do not paste all of it at once and hope. Budget about half an hour the first time, and roughly nothing every time after.

3.1 — What has to be installed

git --version      # any recent version
node --version     # v20 or newer. Next.js 16 and React 19 will not run on v18
npm --version
gh --version       # GitHub CLI - https://cli.github.com
python --version   # 3.12+, only needed for backend issues

gh is not optional here. Claiming an issue, opening the pull request and reading the board all go through it. If it is missing, install it before anything else.

Python is only needed if the issue touches api/ or agent/. A documentation or frontend issue needs Node and nothing more.

3.2 — Log in to GitHub

gh auth status

If that says you are not logged in:

gh auth login

Choose GitHub.com → HTTPS → Yes to authenticate git → Login with a web browser, then paste the one-time code it prints.

This step is skipped more often than any other, and it fails late rather than early: everything looks fine until the first gh command, which then prints "To get started with GitHub CLI, please run: gh auth login" instead of doing the thing. If any gh command produces that message, this is why.

Reading the project board needs one extra scope, which the default login does not grant:

gh auth refresh -s read:project

3.3 — Fork and clone

Everyone contributes through a fork. Nobody gets write access to the repository, and that is the same rule for everyone.

gh repo fork Dpro-at/Tel-Agent --clone
cd Tel-Agent
git remote -v          # expect: origin = your fork, upstream = Dpro-at

gh repo fork --clone sets upstream for you. If git remote -v does not show it:

git remote add upstream https://github.com/Dpro-at/Tel-Agent.git

3.4 — Check the email on your commits

git config user.email

If that address is not on your GitHub account — or your @users.noreply.github.com one — your commits land unlinked: the work gets merged and your name is on nothing.

This is the single most common way somebody does real work here and does not appear in the contributors list, and it is awkward to correct afterwards. Fix it now:

git config user.email "you@example.com"

3.5 — Run what exists

The frontend runs today:

npm --prefix web install
npm --prefix web run dev

Open http://localhost:3000. It redirects to a locale — /en, /de or /ar — and you should land on the sign-in screen. If you see that, the setup worked. Every screen has a state switcher pinned to the top in development; it is stripped from a production build.

The screens read from static fixture modules, so they render without a server. Nothing is wired to anything yet.

The backend does not run, because it does not exist. agent/ and api/ hold six .gitkeep files and two READMEs, and building them is what most of the open issues are. If an issue asks you to run something that is not there, re-read it — the task is almost certainly to create it.

3.6 — Confirm the tooling before you touch code

npx --prefix web tsc --noEmit    # expect: no output
npm --prefix web run lint

Run these before your first edit, not after. If something is already red on a clean clone, that is worth reporting as its own issue — and it is not yours to fix inside an unrelated pull request.

Step 4 — Do the work

git checkout -b <type>/<short-name>

Types: feat/, fix/, docs/, chore/, refactor/, test/. Example: feat/backend-skeleton.

Stay inside the issue. A pull request that does two things gets reviewed as slowly as its harder half. Something else that needs fixing goes in a new issue.

Commits follow Conventional Commits:

feat(api): add health endpoint
docs(contributing): add a what-to-work-on section

Match the code around you — its naming, its comment density, its idiom. A change that reads like it was always there is the goal.

Step 5 — Verify before you open anything

Run the issue's own Verify commands first, then the repository gate for whichever half you touched:

# Python
ruff check . && ruff format --check . && mypy . && pytest

# web/
npm --prefix web run lint
npx --prefix web tsc --noEmit
npm --prefix web run build

Nothing you touched may go red.

Then check by hand:

• No secret, key, token, password or real phone number in the diff.
• No competitor named anywhere, in any language.
• Everything in English.
• If it is visible, screenshots in light and dark, and one in ar if the layout is direction-sensitive.

Do not report the task finished until these actually pass. If something fails and you cannot fix it, say so plainly in the pull request — a known failure stated honestly is useful; a silent one wastes a review cycle.

Step 6 — Open the pull request

git push -u origin <branch>
gh pr create --repo Dpro-at/Tel-Agent --title "<same as the commit>" --body "..."

The body says: what you did, what you deliberately did not do, and how you tested it. Link the issue with Closes #<number>. Paste the output of the Verify commands.

Open it as a draft while it is not ready. Ready for review means you believe it is done.

The CLA. The first pull request cannot be merged until its author has signed the Contributor License Agreement. Expect to be asked.

Step 7 — Review

Expect changes to be requested. It is not a verdict on the person.

Push follow-up commits to the same branch. Do not force-push during a review — the reviewer loses their place in the diff.

It lands as a squash-merge, done by a maintainer. The branch is deleted automatically.

If the work has to stop

Half the people who take an issue never finish, and that is normal. Saying so is a contribution: it returns the task to the pool the same day instead of fourteen days later, which is when an inactive assignment is cleared automatically.

gh issue comment <number> --repo Dpro-at/Tel-Agent --body "I cannot finish this - unassigning so somebody else can take it."

What "done" means

The code works, the tests cover it, the documentation says so, and .env.example lists any variable that was introduced. All four, not three.