Contributing at Synxa IT

These defaults apply to every repository in the org (via this .github repo). A repo may override any file with its own copy.

Every change is reviewed as a design first, then again as code, on a single linked thread. The reviewer comments; the author writes the design. Nothing about who writes it changes where it lives.

            ┌──────────────┐      ┌──────────────┐      ┌──────────────┐
  idea ───▶ │ DESIGN review │ ───▶ │  implement    │ ───▶ │  CODE review  │ ───▶ merge
            └──────────────┘      └──────────────┘      └──────────────┘

1. Open a PR that adds a feature-doc under docs/feature-docs/ (Problem, Goals, Technical Design).
2. The design is reviewed on that PR, as comments, before implementation.
3. Build against the doc; keep the doc in sync as a living document (mid-build design changes go into the doc immediately).
4. A feature PR with no feature-doc and no proper description is sent back, not reviewed.

The feature-doc is durable, versioned design history — it stays in the repo.

The rule is structural — about where the content lives, not who writes it:

1. Issue description = the bug report — Symptom, Steps to reproduce, Expected behavior, Root cause (if known), Impact. Use the Bug report template.
2. The LLD goes in the issue comments — design, approach, acceptance criteria. Not committed to docs/.
3. The fixing PR links the issue ("Fixes #123") and keeps its own description lean — it points to the issue, it does not duplicate the LLD.
4. Code pushed → re-reviewed.

Fixes keep their reasoning attached to the bug, instead of littering the repo with transient fix-docs.

If a fix changes a contract that has an in-repo feature-doc (state machine, API signature, event schema, shared env/auth), the issue holds the fix LLD and the feature-doc is updated in the fixing PR to stay in sync. The living-doc rule always wins for documented contracts.

As the team grows, this keeps quality and context consistent: design errors are caught when they are cheapest, ownership is unambiguous, and every change has a design record exactly where the next person will look for it.