Contributing

We build Sifa ID in the open. The SDK and the lexicons carry the MIT licence, and they are open to anybody. The core service (sifa-api, sifa-web) is source-available, and contributions arrive by invitation. This page gets you from "I would like to help" to a merged pull request.

The canonical rules live in the org guide: CONTRIBUTING in singi-labs/.github and the engineering harness. This page is the practical on-ramp.

What we build toward

Sifa ID builds toward a professional reputation that you earn and own. It comes from real work. The people who know you vouch for it. It travels across the open web, so no single company can gate it or switch it off. Professional life is where we start, not where we stop. The fuller story is on the about page.

Earned, not claimed. Owned by you, built for the open web.

These principles decide what belongs in Sifa. When you weigh a feature or a change, if it works against one of them, it is probably a no:

1. Show your work, do not score it. Real activity and contributions, never ranks, tiers, or leaderboards.
2. Earned from others, not asserted by you. The people who know you verify the credibility that counts. That idea is the core of Sifa, so protect it.
3. You own it, and you can always leave. Every feature keeps your data, identity, and graph portable. If it cannot leave, it does not ship.
4. Current by default, not by chore. Prefer pulling in real activity over asking people to maintain a profile by hand.
5. Honest over flattering. No vanity metrics, no dark patterns, nothing that inflates a number for its own sake.
6. Open rails, no landlord. We build on open standards, host in Europe, and stay portable. We do not rebuild the lock-in that we replace.
7. Meet people where they already are. Work with the open web people already use.

We will never build these, whatever the pull:

• reputation scores and leaderboards
• borrowed endorsements in the costume of a verification
• growth dark patterns and lock-in
• surveillance, and sales of member data
• puzzles or games that farm attention
• a feature-for-feature clone of the old professional network

The stack

Sifa is TypeScript end to end: Fastify, PostgreSQL, and Valkey behind sifa-api, Next.js with React and Tailwind in sifa-web, all built on AT Protocol. The credits page has the full list, down to the infrastructure, editors, and open datasets we build on.

Finding something to work on

Start with issues labelled good first issue, which are small, well-scoped, and a good way to learn the codebase:

• Across all of Sifa: open good first issues in singi-labs
• By repo: sifa-sdk · sifa-api · sifa-web
• Want more depth? Swap the label for help wanted.

You see issues only in the repos that you can reach. The SDK and the lexicons are public. The core repos appear after we add you.

Claim it first: comment on the issue to say that you take it, so two people do not build the same thing. No issue for your idea? Open one. Agree the scope before you write code.

Local setup

You will need Node (current LTS), Docker + Docker Compose, and Git. The exact commands (package manager, services, env vars) live in each repo's README.md and AGENTS.md, which are the source of truth:

• sifa-sdk: TypeScript library. Clone, install, test.
• sifa-api: backend. Clone, pnpm install, pnpm services:up (PostgreSQL + Valkey), pnpm db:migrate, pnpm dev.
• sifa-web: frontend. Clone, pnpm install, pnpm dev (needs sifa-api running).

AT Protocol auth is OAuth, never app passwords, an org-wide rule with no exceptions.

Before you open a PR, run the repo's checks locally:

pnpm test
pnpm lint
pnpm typecheck

The workflow

1. Branch from main: git checkout -b feat/short-description. One branch, one change. Never push to main.
2. Build it with tests. The test suite is the contract.
3. Open a PR, link the issue (Closes #NN), fill the checklist.
4. Sign the CLA on your first PR. A bot asks you in a comment. Reply once, and the signature covers all your later PRs.
5. Automated gates run: a secret scan, and a blocking AI reviewer that posts a comment. Address anything it flags and push (it re-runs).
6. A maintainer reviews and merges (squash). You cannot merge your own PR.

Commits follow Conventional Commits: type(scope): description (feat, fix, docs, test, refactor, chore, ci).

The standards

The AI reviewer and maintainers both enforce the engineering standards. The essentials: strict TypeScript with no any, Zod on every input, tests with every change, sanitised user content, WCAG 2.2 AA on the UI, and no console.*. Reuse an existing UI primitive before you add a new one.

If you use a coding agent (Claude Code or similar), drop agent-instructions.md into your clone as CLAUDE.md / AGENTS.md to keep it inside the house rules.