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