Contributing & Conventions¶

How we collaborate day-to-day: pull-request process, code-review etiquette, and pre-flight checklists.

Looking for how code reaches production — branches, previews, the staging freeze, releases, hotfixes? That's the Release Workflow, the single source of truth for the flow itself. This page covers the conventions layered on top of it.

Branching & flow¶

Shootify uses AtomiqFlow, a PR-based draft/ready release model. The full model — the branch table, cross-repo previews, the DRAFT/READY staging freeze, releases, and hotfixes — lives in Release Workflow, the source of truth. Don't duplicate it here; link to it.

The one convention you need before that page: name branches <ISSUE-CODE>/<short-slug> — e.g. SAR-1234/forgot-password. The issue-code prefix is how cliq finds your branch when it builds a cross-repo preview, so use it consistently across every repo you touch.

For the inner loop before a preview, run an isolated local stack with hot reload keyed to your task — cliq local up <slug> --task <ISSUE-CODE> (see cliq → local). Multiple slugs run in parallel, each on its own DB / Redis / ports / storage, so you can keep one task alive while validating another. Reach for cliq preview create (next section) once you need a public URL or real-OAuth / R2-transform behavior.

Commit and PR title invariant¶

Commit headers and PR titles use type(scope)[!]: subject, with a required lowercase scope and ! for incompatible public contracts. The exact 11 types, header rules, final-diff classification process, contract surfaces, and semantic-version mapping live only in Release Workflow → Commit and version contract.

Classify what the final diff implements. Do not infer the header from an issue, branch, history, or requested version bump, and do not let supporting tests or documentation override the primary effect.

Pull Request Process¶

Creating a Pull Request¶

Push your branch to origin
Open PR via GitHub (or gh pr create)
Fill in the template completely

PR Template¶

## Summary

Brief description of the changes (2-3 sentences max).

## Changes

- Bullet point list of what changed
- Be specific about files/components affected
- Note any breaking changes

## Testing

- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
- [ ] Edge cases considered

## Screenshots

(If UI changes, include before/after screenshots)

## Related Issues

Closes #123

PR Requirements¶

Requirement	Details
Title	Contract header format, at most 72 characters (e.g., `feat(auth): add SSO support`)
Description	Complete template with summary, changes, testing
Size	Under 400 lines changed (split large PRs)
Tests	New code must have tests
CI	All checks must pass
Review	At least 1 approval required

Linking to Issues¶

Use GitHub keywords to auto-close issues:

Closes #123
Fixes #456
Resolves #789

Code Review Guidelines¶

What Reviewers Look For¶

Category	Questions to Ask
Correctness	Does it do what it claims? Are edge cases handled?
Design	Does it follow existing patterns? Is it maintainable?
Simplicity	Is there unnecessary complexity? Can it be simpler?
Testing	Are tests adequate? Do they test behavior, not implementation?
Security	Any injection risks? Auth checks in place? Sensitive data exposed?
Performance	Any N+1 queries? Unnecessary loops? Memory issues?

Giving Constructive Feedback¶

Do: - Ask questions: "What happens if X is null?" - Suggest alternatives: "Consider using X instead of Y because..." - Acknowledge good work: "Nice approach to handling the edge case" - Be specific: Point to exact lines, provide examples

Don't: - Be vague: "This is wrong" - Be personal: "You don't understand..." - Nitpick style when linters exist - Block on preferences vs. real issues

Feedback Prefixes¶

Use these prefixes to clarify intent:

Prefix	Meaning
`blocking:`	Must be fixed before merge
`suggestion:`	Optional improvement
`question:`	Seeking clarification
`nit:`	Minor style issue, non-blocking
`thought:`	Not actionable, just sharing perspective

Responding to Reviews¶

Address all comments before requesting re-review
Reply to each comment (resolved, fixed, or explained)
Don't take feedback personally—it's about the code
If you disagree, explain your reasoning

Response Time Expectations¶

Action	Target Time
Initial review	Within 1 business day
Follow-up review	Within 4 hours
Author response to feedback	Within 1 business day

CI checks¶

Every PR into dev must go green before it can merge. Two checks gate it directly:

ci-checks — lint + format + types and the test suites (Ruff/MyPy for Python; ESLint/Prettier/tsc for TypeScript; pytest + Jest).
check-title — enforces the authoritative PR title contract for feature and hotfix PRs.
Contract reviews — inspect each feature/hotfix diff and the aggregate release candidate for incompatible public contracts.

The full pipeline — security scanning, image build/push, and the staging/prod deploy triggers — is documented in CI/CD, with the deploy side covered by Release Workflow. Don't restate the stages here.

gh pr checks            # status on your PR
gh run view <run-id>    # inspect a specific run
gh run rerun <run-id>   # re-run failed checks

Releases & versioning¶

How a service release is cut, frozen, shipped, rolled back, and semantically versioned is documented in Release Workflow. All three service repositories derive strict semantic tags from eligible final commit headers with identical bump semantics. Backend and webapp first bootstrap at v1.0.0; compute-server intentionally starts from its current project.version, 0.1.0. prod-* tags identify deployments and are not semantic-version inputs. The docs repository follows the header rules but not the service release automation.

Hotfix review expectations¶

The mechanics of a hotfix — when one is warranted, branching from main, the PR to main, and the mandatory merge-back into dev — are in Release Workflow → Bug found in prod. What's specific to how we review and follow up on a hotfix lives here.

Hotfix Contract Review¶

Hotfixes are reserved for critical production issues that cannot wait for the normal cycle, but urgency does not preclassify them as fix or patch and does not waive title, contract-review, test, or approval gates. Classify the complete final diff, use ! for any incompatible public contract, and keep the direct-to-main change as small as possible.

Post-Hotfix¶

Create follow-up issue for proper fix if hotfix was a band-aid
Schedule retrospective if hotfix was for preventable issue
Update monitoring/alerting if issue wasn't caught

Development Checklist¶

Before Starting Work¶

Issue exists and is assigned to you
Requirements are clear (ask if not)
Branch created from latest dev
Local environment is working

Before Committing¶

Code compiles/runs without errors
Tests pass locally
Linting passes (ruff check, bun run lint)
No secrets or credentials in code
No console.log or debug statements

Before Opening PR¶

Final diff and public contract surfaces were inspected before choosing the header
All commit headers follow the authoritative contract
Branch is rebased on latest dev
PR template is filled out completely
Tests added for new functionality
Documentation updated if needed
Self-reviewed the diff