Contribution Guide

How a feature travels from an idea to merged code. Read this before picking up work.

1. Where things live

Repository	Holds	Stack
evuventures/Salesfam	This documentation site — functional requirements, domain model, API contracts, architecture	Docusaurus
evuventures/salesfam-back	Backend service and the OpenAPI specification	Node.js, Express, TypeScript, Prisma
evuventures/salesfam-front	Web application	Next.js, TypeScript, Tailwind CSS

See Technology Stack for the complete list of approved technologies. Don't introduce a new dependency without raising it first.

2. How work is tracked

Every feature is a card on the GitHub Project board, and every card carries the same three-step checklist:

- [ ] Functional Requirement Documentation
- [ ] OpenAPI definition contract
- [ ] Programming

You choose the feature. You don't choose the step. Pick whichever feature you want to work on, then start from the first step that isn't marked done. Each step depends on the one before it being finished and merged.

When a step's pull request is merged, mark it [OK] on the card:

- [OK] Functional Requirement Documentation
- [ ] OpenAPI definition contract
- [ ] Programming

That mark is the signal to everyone else. It's how the next contributor knows what is safe to pick up without asking, so update the card as part of finishing the step — not later.

A step opens only when the previous one is merged

Not when it's written, not when the PR is open — when it's merged. Starting the OpenAPI contract while the Functional Requirement is still in review means rewriting the contract every time a reviewer changes the requirement.

3. The flow at a glance

4. Step 1 — Functional Requirement Documentation

Repository: evuventures/Salesfam

Before any code exists, the behavior has to be written down. A requirement that isn't written is a requirement two people will implement differently.

Read the repository's README.md first — it's the source of truth for this workflow, and it covers the branch → form → preview → PR sequence in detail. The short version:

1. Branch off main, named after the FR you're working on.
2. Run npm run new:fr and fill in the form. Don't hand-write the Markdown or the frontmatter — the form handles file placement, numbering and structure for you.
3. Preview with npm start and confirm it renders.
4. Open a pull request into main.

A Functional Requirement is finished when it states the Trigger, what the system shall do, any state transition, and Acceptance Criteria as PASS/FAIL statements. Someone who has never seen the feature should be able to tell, from the criteria alone, whether an implementation is correct.

main is protected

Everything goes through a pull request. See the README for the exact branch and commit conventions.

5. Step 2 — OpenAPI definition contract

Repositories: evuventures/salesfam-back (the spec) and evuventures/Salesfam (the documentation)

This is the one step that is not done alone. Frontend and backend get together and agree the contract — endpoints, request and response shapes, status codes, error format — against the Functional Requirement that was just merged. It's a conversation, not a handoff.

The step produces two things:

Output	Where	Who
The OpenAPI specification	salesfam-back, as a draft pull request	Backend
The contract, documented	Salesfam docs, chapter 05 — API Endpoints, via npm run new:fr	Backend, with frontend reviewing

Why a draft PR

The draft PR exists so the frontend doesn't have to wait. As soon as it's open, frontend copies the contract out of it and starts building against it, while backend implements the same contract on the other side. Both sides work asynchronously, from the same agreed shape, and neither one blocks the other.

The contract is a commitment

Once agreed, both sides are building against it. Changing it mid-development silently breaks whoever isn't in the room. If it has to change, say so in the channel first, update the draft PR and the docs, and make sure the other side has seen it before you continue.

6. Step 3 — Programming

Repositories: evuventures/salesfam-back and evuventures/salesfam-front

Both sides implement the contract in parallel, each in their own repository, each on their own branch. Frontend builds against the contract as specified — if the real endpoint doesn't exist yet, mock it; don't wait for it.

Merge order

Backend merges first. Frontend merges second. Always, and for one reason: the frontend depends on endpoints that must already exist. Merging the other way around ships a UI that calls nothing.

1. Backend's pull request is reviewed and merged.
2. Frontend's pull request is reviewed and merged.
3. Both are verified working together.

If they work, mark [OK] and the feature is done.

If they don't, roll back and review. Don't leave a broken integration on main while it's being debugged, and don't patch forward under time pressure — revert first, diagnose second. Most failures at this point trace back to the contract having drifted on one side, so start there.

7. Testing

Every developer is responsible for the unit tests covering the code they write. Tests are part of the work, not a separate task that happens afterwards.

If you genuinely don't have time to write them, don't quietly skip them. Do all three of these:

1. Raise it — say so, in the pull request and to the team, before it's merged.
2. Document it — state plainly what is not covered and why.
3. Open an issue — so someone else can pick the tests up, with enough context to do it without asking you.

Untested code that everyone knows about is a tracked debt. Untested code nobody mentioned is a trap for the next person.

8. Before you open a pull request

• The step you're on is the first unfinished one on the card.
• The previous step was merged, not just submitted.
• Documentation changes preview correctly (npm start) and the build passes (npm run build).
• Unit tests are written — or raised, documented and issued, per section 7.
• The PR says which feature and which step it belongs to.
• After merging: mark the step [OK] on the Project board.