Contributing

Sifa ID is built in the open. The SDK and lexicons are MIT-licensed and open to anyone. The core service (sifa-api, sifa-web) is source-available, contributed to by invitation. This page gets you from "I'd 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're building toward

Sifa ID is building toward a professional reputation you earn and own: earned from real work, vouched for by the people who'd know, and portable 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's probably a no:

1. Show your work, don't score it. Real activity and contributions, never ranks, tiers, or leaderboards.
2. Earned by others, not asserted by you. The credibility that counts is verified by people who'd know. That's 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 can't leave, it doesn't 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 don't recreate the lock-in we're replacing.
7. Meet people where they already are. Work with the open web people already use.

And the things we won't build, whatever the pull: reputation scores or leaderboards, borrowed endorsements dressed up as verified, growth dark patterns or lock-in, surveillance or selling member data, puzzles or games to farm attention, and 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'll only see issues in repos you have access to. The SDK and lexicons are public, the core repos appear once you've been added.

Claim it first: comment on the issue to say you're picking it up, so two people don't build the same thing. No issue for your idea? Open one and discuss the scope before writing code.

Local setup

You'll 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 comments asking you to. Reply once and it's recorded for all future 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 can't 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: TypeScript strict (no any), validate inputs with Zod, tests with every change, sanitize user content, accessibility (WCAG 2.2 AA) for UI, no console.*, and reuse existing UI primitives before adding new ones.

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.