Skip to main content

Contributing

How to land code in GreekManage.

Branch naming​

feature/issue-<N>-<short-description>
fix/issue-<N>-<short-description>
chore/<short-description>
docs/<short-description>

Examples:

  • feature/issue-148-pnm-rate-limit
  • fix/issue-152-election-runoff-tie
  • chore/upgrade-django-6-1
  • docs/dev-onboarding

Always branch from main. Sync regularly with git pull --rebase origin main.

Pull request workflow​

  1. Open a draft PR early. Even with a few commits, draft PRs let CI start running and reviewers see direction.
  2. Reference the issue. PR body must include Closes #N so the issue auto-closes on merge.
  3. Write tests. Targets: backend ≥80% coverage; frontend ≥70%. PRs that drop coverage are blocked by the SonarQube quality gate.
  4. Run security checks locally before pushing. 
    npm run security:full
  5. Pass CI. All required checks must be green:
    • Backend tests (pytest, scoped to changed apps)
    • Frontend tests (Vitest) + build
    • Android Gradle build
    • SAST (Bandit + Semgrep)
    • SCA (pip-audit + npm audit)
    • Trivy filesystem scan
    • SonarQube quality gate
    • E2E smoke (@smoke tagged tests + ZAP API + ZAP baseline)
    • Claude Code Review (advisory; doesn't block)
  6. Get one approving review. Repo enforces this on main.
  7. Squash and merge. Use the GitHub "Squash" button to keep main history clean.

PR description template​

## What
Short summary of the change.

## Why
The problem this solves or feature this enables. Link the issue.

## How
Notable implementation choices and trade-offs.

## Test plan
- [ ] Unit tests added for new logic
- [ ] E2E test added if user-facing
- [ ] Manual QA notes

Closes #N

Code review​

We review for:

  • Correctness — does it do what the issue asked?
  • Tests — are edge cases covered?
  • Security — auth checks, input validation, no secrets in code
  • Performance — N+1 queries, missing indexes, unbounded list ops
  • Multi-tenancy — does it respect RLS / OrganizationContextMiddleware?
  • API design — is the endpoint shape consistent with neighbors?
  • Naming + readability

Reviewers leave inline comments and a top-level approval / changes-requested. Authors respond to every comment (resolve, fix, or push back with reasoning).

Style​

  • Backend: black for formatting (auto-applied via pre-commit), ruff for linting, type hints on public APIs
  • Frontend: prettier for formatting, eslint for linting, strict TypeScript (no any unless commented why)
  • SQL in migrations: lowercase keywords, snake_case identifiers
  • Mermaid diagrams in docs: use the existing color tokens (#334155 primary)

Adding a new Django app​

  1. cd backend && python manage.py startapp <name> apps/<name>
  2. Add apps.<name> to INSTALLED_APPS in backend/greekmanage/settings.py
  3. Create apps/<name>/urls.py, register in backend/greekmanage/urls.py
  4. Add apps/<name>/permissions.py if app-specific permissions are needed
  5. Define your models — inherit from apps.common.models.TimeStampedModel if you want created_at / updated_at for free
  6. Run python manage.py makemigrations <name> and review the migration
  7. Document the app at docs-site/docs/developers/apps/<name>.mdx
  8. Add tests under backend/apps/<name>/tests/

Adding a new endpoint​

  1. Define a serializer in apps/<app>/serializers.py
  2. Add a viewset / view in apps/<app>/views.py with permission_classes
  3. Wire it up in apps/<app>/urls.py
  4. Write at least one test in apps/<app>/tests/test_<feature>.py
  5. Regenerate the OpenAPI schema and commit it: 
    python manage.py spectacular --file ../docs-site/openapi/greekmanage.yaml
    cd ../docs-site && npm run docusaurus gen-api-docs all
  6. The new endpoint shows up in the API reference automatically

Adding a frontend page​

  1. Create the route in frontend/src/router.tsx
  2. Create the page component in frontend/src/pages/<role>/<page>.tsx
  3. If admin-only or module-gated, wrap with <RoleGuard> / <ModuleGuard>
  4. Add a Vitest test in the same folder if logic-heavy
  5. If user-facing, add a docs page under docs-site/docs/<role>/<page>.mdx

Security gates​

Some changes touch security-sensitive surfaces and require extra review:

  • Auth flows (login, SSO, JWT) — review by 2 maintainers
  • Permission classes — review by 2 maintainers
  • Encryption / key handling — review by maintainer + log entry in SECURITY.md
  • Audit log changes — review by maintainer; never delete log entries
  • Payment processing — PCI-relevant; review by maintainer + manual QA in staging

Release process​

  1. Bump backend/VERSION and frontend/package.json to the new SemVer
  2. Update CHANGELOG.md with the new entry (Added / Changed / Fixed sections)
  3. Open a release PR titled Release vX.Y.Z
  4. Squash-merge after approval
  5. Tag the release: git tag vX.Y.Z && git push origin vX.Y.Z
  6. Production deploy: separate workflow, manually triggered (not automatic on tag)

Reporting security issues​

Do not open a public issue for a security vulnerability. Email security@greekmanage.com with:

  • A description of the vulnerability
  • Reproduction steps
  • Impact assessment

We respond within 24 hours and follow SECURITY.md for disclosure.

Code of conduct​

Treat collaborators as you'd want to be treated. Disagree on technical merits; don't make it personal. Reviewers and authors share the same goal.

Help​

  • Architecture questions: tag @maintainers in your PR
  • Stuck on local setup: see Getting started — most issues are env vars
  • Slack / Discord: link in repo README