Skip to main content

Contributing to Claw GRC

Thank you for your interest in contributing to Claw GRC. This guide covers the development workflow, coding standards, and processes for getting your changes merged.

Development Workflow​

1. Create a Branch​

Branch from main using the naming convention:

git checkout -b feat/add-evidence-expiry-alerts
git checkout -b fix/rls-policy-agents-table
git checkout -b chore/update-go-dependencies
git checkout -b docs/add-api-rate-limiting-docs
PrefixUse When
feat/Adding a new feature or capability
fix/Fixing a bug
chore/Maintenance, dependency updates, refactoring
docs/Documentation changes only
test/Adding or updating tests

2. Make Your Changes​

Follow the coding standards for the service you are modifying (see below).

3. Commit with Conventional Commits​

# Features
git commit -m "feat: add evidence expiry notification system"

# Bug fixes
git commit -m "fix: prevent RLS bypass on agents table for owner role"

# Maintenance
git commit -m "chore: update Go dependencies to latest patch versions"

# Documentation
git commit -m "docs: add API rate limiting documentation"

# Tests
git commit -m "test: add integration tests for MCP handshake"

Commit message format:

`<type>`: `<concise description>`

[optional body explaining what and why]

[optional footer with breaking changes or issue references]

4. Push and Create a PR​

git push -u origin feat/add-evidence-expiry-alerts

Create a pull request against main with:

  • A clear title following the conventional commit format
  • A description of what changed and why
  • Any testing instructions for reviewers

5. Code Review​

All PRs require at least one review before merging. Reviewers check:

  • Code correctness and security implications
  • Test coverage (see Testing Requirements below)
  • Adherence to coding standards
  • Database migration safety (if applicable)

Coding Standards​

Go Services (API Gateway, Compliance Engine)​

  • Go 1.24, net/http standard library (no web frameworks)
  • Structured logging with log/slog
  • Raw SQL with lib/pq (parameterized queries only)
  • Error handling: wrap errors with context using fmt.Errorf("operation: %w", err)
  • Run go vet ./... before committing

Python Services (Security Engine, Agent Protocol)​

  • Python 3.13, FastAPI, Pydantic v2
  • SQLAlchemy async for database access
  • Type hints on all function signatures
  • Do not use ConfigDict(strict=True) on request models with StrEnum fields (Pydantic bug)
  • Run ruff check . before committing

Frontend (Web)​

  • Next.js 16.2, React 19, TypeScript 5.9
  • Tailwind CSS 4, shadcn/ui v4
  • Use export function proxy() in src/proxy.ts (not middleware.ts)
  • Use <Context.Provider value={...}> (not <Context value={...}> shorthand)
  • shadcn/ui v4 uses render prop, not asChild
  • Build with NODE_ENV=production npx next build

Database​

  • All migrations in db/migrations/ using golang-migrate format
  • Every tenant table must have org_id and an RLS policy
  • New tenant tables must include FORCE ROW LEVEL SECURITY
  • Seed data must be idempotent (ON CONFLICT DO UPDATE)
  • Use make migrate-create NAME=your_migration to create migration files

Testing Requirements​

Minimum Coverage​

ServiceRequirement
Go servicesUnit tests for all handlers and business logic
Python servicesUnit tests + integration tests for DB operations
FrontendComponent tests for complex UI, unit tests for API client

Running Tests​

# All tests
make test

# Individual services
cd apps/api-gateway && go test ./...
cd apps/security-engine && python -m pytest
cd apps/web && npx vitest run

What to Test​

  • Business logic -- All calculations, validations, and transformations
  • API handlers -- Request parsing, response formatting, error handling
  • Database operations -- CRUD operations with RLS context
  • Authentication -- JWT validation, API key verification
  • Edge cases -- Empty inputs, boundary values, concurrent operations

Security Considerations​

  • Never commit secrets -- Use environment variables and GCP Secret Manager
  • Parameterize all queries -- Never use string interpolation in SQL
  • Validate all inputs -- Use Pydantic models (Python) or explicit validation (Go)
  • Check RLS context -- Every handler that touches tenant data must call WithOrgContext() or set_rls_context()
  • Strip internal headers -- The API Gateway must strip and re-set all internal headers

Pre-Push Hook​

The repository includes a pre-push hook that automatically runs:

  1. go vet and go test for Go services
  2. ruff check and pytest for Python services
  3. TypeScript type checking and Vitest for the frontend

All checks must pass before the push is allowed. This ensures that broken code never reaches the remote repository.

Getting Help​

  • Open a GitHub issue for bugs or feature requests
  • Tag your issue with the appropriate labels (bug, enhancement, documentation)
  • For security vulnerabilities, email security@clawgrc.com directly