Development Workflows¶

End-to-end guide for the Sartiq development lifecycle, from issue creation to production deployment.

Git Workflow¶

Branch Naming¶

All branches must follow this naming convention:

Prefix	Purpose	Example
`feature/`	New functionality	`feature/user-preferences`
`fix/`	Bug fixes	`fix/login-redirect-loop`
`refactor/`	Code improvements (no behavior change)	`refactor/auth-service-cleanup`
`docs/`	Documentation changes	`docs/api-authentication`
`chore/`	Maintenance tasks	`chore/update-dependencies`
`test/`	Test additions or fixes	`test/payment-edge-cases`

Use kebab-case for branch names. Keep them descriptive but concise.

Branch Model¶

We use a 4-branch promotion model:

Branch	Purpose	Deploys To	Merge Strategy
`main`	Production-ready code, protected	Production	Merge from `staging`
`staging`	QA / pre-production validation	Staging environment	Merge from `dev`
`dev`	Integration branch for all work	CI checks only	Squash-merge from feature branches
`feature/`, `fix/`, etc.	Short-lived task branches	N/A	Branch from `dev`, squash-merge back

Branch protections (apply to main, staging, and dev):

No direct pushes (all changes via PR)
Requires at least 1 approval
Requires CI checks to pass
Requires branch to be up-to-date

Feature Branch Workflow¶

# 1. Start from latest dev
git checkout dev
git pull origin dev

# 2. Create feature branch
git checkout -b feature/user-preferences

# 3. Make changes and commit
git add .
git commit -m "feat: add user preferences API"

# 4. Push and create PR targeting dev
git push -u origin feature/user-preferences
# Open PR via GitHub UI or CLI (target branch: dev)

# 5. After approval, squash and merge into dev
# Use "Squash and merge" for clean history

# 6. Clean up
git checkout dev
git pull origin dev
git branch -d feature/user-preferences

Rebasing vs Merging¶

Policy: Rebase feature branches onto dev before merging.

# Update feature branch with latest dev
git checkout feature/my-feature
git fetch origin
git rebase origin/dev

# Resolve conflicts if any, then continue
git add .
git rebase --continue

# Force push after rebase (only on feature branches!)
git push --force-with-lease

When to merge instead: Only for long-lived branches with multiple contributors.

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/CD Pipeline¶

Pipeline Stages¶

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  Lint &  │───▶│   Test   │───▶│   Scan   │───▶│  Build   │───▶│   Push   │───▶│  Deploy  │
│  Format  │    │          │    │          │    │          │    │          │    │          │
└──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘
     │               │               │               │               │               │
     ▼               ▼               ▼               ▼               ▼               ▼
  Ruff, ESLint   pytest, Jest    Security       Docker build    Push image     Staging/Prod
  Prettier       Coverage        scanning       Type check      to registry
  MyPy

Full pipeline details

See CI/CD Pipeline for the complete pipeline configuration including security scanning and image registry steps.

Stage 1: Lint & Format¶

Checks that run on every push:

Check	Tool	Failure Reason
Python formatting	Ruff	Unformatted code
Python linting	Ruff	Lint violations
Python types	MyPy	Type errors
JS/TS formatting	Prettier	Unformatted code
JS/TS linting	ESLint	Lint violations
TS types	tsc	Type errors

Stage 2: Test¶

Test Suite	Tool	Coverage Target
Backend unit	pytest	80%+ on `app/`
Backend integration	pytest + httpx	N/A
Frontend unit	Jest	80%+ on `src/`
Frontend component	Testing Library	N/A

Stage 3: Build¶

Docker image builds for backend and frontend
Build failures block merge
Images tagged with commit SHA

Stage 4: Scan¶

Security vulnerability scanning on dependencies and container images
Blocks pipeline on critical or high-severity findings

Stage 5: Push¶

Pushes built Docker images to the container registry
Images tagged with commit SHA and branch name

Stage 6: Deploy¶

Trigger	Target
PR squash-merge to `dev`	Runs CI (lint, test, scan, build)
Merge `dev` → `staging`	Deploys to staging environment
Merge `staging` → `main`	Deploys to production

Checking CI Status¶

# Via GitHub CLI
gh pr checks

# View specific workflow run
gh run view <run-id>

# Re-run failed checks
gh run rerun <run-id>

Release Process¶

Versioning Strategy¶

We use Semantic Versioning:

MAJOR.MINOR.PATCH

1.0.0 → 1.0.1  (patch: bug fix)
1.0.1 → 1.1.0  (minor: new feature, backwards compatible)
1.1.0 → 2.0.0  (major: breaking change)

Changelog Maintenance¶

Update CHANGELOG.md with every release:

# Changelog

## [1.2.0] - 2024-03-15

### Added
- User preference settings (#123)
- Dark mode support (#124)

### Changed
- Improved error messages for auth failures (#125)

### Fixed
- Login redirect loop on expired tokens (#126)

### Security
- Updated dependencies for CVE-2024-XXXX (#127)

Release Workflow¶

# 1. Ensure dev is up to date and passing CI
git checkout dev
git pull origin dev

# 2. Create release branch from dev
git checkout -b release/1.2.0

# 3. Update version numbers
# - backend/pyproject.toml
# - frontend/package.json

# 4. Update CHANGELOG.md

# 5. Commit version bump
git add .
git commit -m "chore(release): prepare 1.2.0"

# 6. Merge release branch into dev, then promote dev → staging
gh pr create --title "chore(release): 1.2.0" --base dev
# After merge, promote dev to staging for QA validation:
# Open PR: dev → staging

# 7. After QA sign-off, promote staging → main
# Open PR: staging → main

# 8. Tag the release on main
git checkout main
git pull origin main
git tag -a v1.2.0 -m "Release 1.2.0"
git push origin v1.2.0

# 9. Create GitHub release
gh release create v1.2.0 --title "v1.2.0" --notes-file CHANGELOG.md

Deployment to Production¶

Merge staging → main triggers the production deployment pipeline
Deployment requires manual approval in GitHub Actions
Rollback via re-deploying previous tag if issues arise

Hotfix Workflow¶

When to Use¶

Hotfixes are for critical production issues that cannot wait for the normal release cycle:

Security vulnerabilities
Data corruption bugs
Complete feature breakage
Compliance issues

Hotfix Process¶

# 1. Create hotfix branch from production tag
git checkout v1.2.0
git checkout -b hotfix/1.2.1-fix-auth-bypass

# 2. Make the minimal fix
# ... make changes ...
git commit -m "fix(auth): prevent token reuse after logout"

# 3. Create PR targeting main
gh pr create --title "fix(auth): prevent auth bypass [HOTFIX]" --base main

# 4. Fast-track review (1 reviewer minimum)
# - Mark PR as critical
# - Ping on-call reviewer directly

# 5. After merge, create patch release
git checkout main
git pull origin main
git tag -a v1.2.1 -m "Hotfix: auth bypass"
git push origin v1.2.1

Fast-Track Review¶

Hotfix PRs have relaxed requirements:

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