Contributing & Conventions¶

How we collaborate day-to-day: commit format, the pull-request process, code-review etiquette, and the 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.

Commit Standards¶

Conventional Commits¶

All commits must follow the Conventional Commits format:

<type>(<scope>): <description>

[optional body]

[optional footer]

Commit Types¶

Type	When to Use
`feat`	New feature for the user
`fix`	Bug fix for the user
`docs`	Documentation only changes
`style`	Formatting, missing semicolons, etc. (no code change)
`refactor`	Code change that neither fixes a bug nor adds a feature
`test`	Adding or correcting tests
`chore`	Maintenance tasks, dependency updates
`perf`	Performance improvements
`ci`	CI/CD configuration changes
`build`	Build system or external dependencies

Commit Message Structure¶

feat(auth): add password reset functionality

Implement password reset flow with email verification.
Users can request a reset link that expires after 24 hours.

- Add password reset request endpoint
- Add password reset confirmation endpoint
- Add email template for reset links
- Add tests for reset flow

Closes #123

Rules: - Subject line: imperative mood, no period, max 72 characters - Body: wrap at 72 characters, explain "what" and "why" - Footer: reference issues, breaking changes

Examples¶

Good commits:

feat(api): add user preferences endpoint
fix(auth): prevent token reuse after logout
docs(setup): add Docker troubleshooting section
refactor(services): extract email sending logic
test(api): add edge cases for payment flow
chore(deps): update fastapi to 0.111.0

Bad commits:

update stuff                    # Not descriptive
Fixed the bug                   # Not conventional format
feat: Add new feature.          # Period, capitalized
WIP                             # Work in progress shouldn't be committed

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	Conventional commit format (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 conventional PR title format.

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 release is cut, frozen, shipped, and rolled back is documented in Release Workflow — the always-present release PR, the DRAFT/READY staging freeze, the merge-commit to main, and the prod-YYYY-MM-DD-HHMMSS tags you roll back to.

On versioning: semantic versioning (MAJOR.MINOR.PATCH) and changelog automation are the intended scheme but are not currently enabled — they'll be planned separately. Today a release is identified by its prod-* timestamp tag, not a semver number.

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.

Fast-Track Review¶

Hotfix PRs have relaxed requirements, because they're reserved for critical production issues (security holes, data corruption, total feature breakage, compliance) that can't wait for the normal cycle:

Normal PR	Hotfix PR
1+ reviewers	1 reviewer
All tests pass	Critical tests pass
Full CI pipeline	Abbreviated pipeline
Normal response time	Immediate response

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¶

All commits follow conventional format
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