Contributing to Cruvero

Thanks for contributing.

This file defines the expected contribution flow and quality bar for all changes.

Contribution Flow (Expected)​

1. Start with a conversation:
   • For new features, major behavior changes, or architecture work, open a GitHub Discussion first.
   • For bugs and scoped improvements, open a GitHub Issue first.
2. Align scope before coding:
   • Capture acceptance criteria in the issue/discussion.
   • Confirm in-scope vs out-of-scope before implementation.
3. Fork and branch:
   • Fork the repository.
   • In your fork, create a feature branch from dev.
4. Implement with tests and docs updates.
5. Open a Pull Request from your fork to main:
   • Link the issue in the PR description (for example: Closes #123).
   • Keep one PR focused on one issue.

Engineering Standards​

Go Standards​

• Keep code gofmt-formatted.
• Pass all backend checks:
  • go test ./... -count=1
  • go vet ./...
  • staticcheck ./...
  • golangci-lint run ./...
• Maintain license headers on Go files (enforced by goheader in .golangci.yml).
• Follow repository conventions:
  • Deterministic Temporal workflow logic in workflows.
  • Side effects in activities.
  • Env-driven config (CRUVERO_*), no ad-hoc config files.

React / JS / TS Standards​

Frontend code lives under cmd/ui/frontend/.

• TypeScript must compile in strict mode (npm run build runs tsc --noEmit).
• ESLint must pass:
  • npm run lint
• Keep formatting consistent with Prettier:
  • npm run format (or equivalent formatting in your editor)
• Tests must pass:
  • npm run test
• For UI behavior changes, include/adjust unit tests and, when appropriate, Playwright coverage.

Test and Coverage Requirements​

Coverage is a hard gate.

• Backend: minimum 80% per package (default threshold in coverage-thresholds.json).
  • Run: ./scripts/check-coverage.sh
• Frontend: minimum 80% for lines/branches/functions/statements (Vitest config).
  • Run: cd cmd/ui/frontend && npx vitest --coverage --reporter=default

Duplication Budget​

• Keep code duplication under 2%.
• Prefer extracting shared logic over copy/paste.
• If duplication is intentional, document why in the PR.

Security and Dependency Hygiene​

• No known security vulnerabilities in merged code.
• Backend dependency scan must be clean:
  • govulncheck ./...
• Frontend dependency audit must be clean at high severity or above:
  • cd cmd/ui/frontend && npm audit --audit-level=high
• Never commit secrets, tokens, credentials, or private keys.
• If you discover a vulnerability, use private disclosure to maintainers (do not post public exploit details).

PR Expectations​

Every PR should include:

• A clear summary of what changed and why.
• A linked issue/discussion.
• Validation output for relevant checks.
• Risk notes (behavioral, migration, config, and rollout impact).
• Docs updates when behavior, commands, config, or APIs changed.

Database and API Changes​

If your change includes schema/API changes:

• Add forward and rollback SQL migrations (.up.sql and .down.sql).
• Keep migration numbering sequential.
• Update docs (docs/manual/ and related READMEs) to reflect new behavior.
• Call out compatibility or migration risks in the PR.

Commit and Change Hygiene​

• Keep commits focused and reviewable.
• Prefer conventional commit style:
  • feat(scope): ...
  • fix(scope): ...
  • docs: ...
• Do not include AI co-author trailers.

Pre-PR Checklist​

• Issue or discussion exists and scope is aligned
• PR is from fork branch and links the issue
• go test ./... -count=1 passes
• go vet ./... passes
• staticcheck ./... passes
• golangci-lint run ./... passes
• ./scripts/check-coverage.sh passes (80%+ per package)
• Frontend checks pass (npm run lint, npm run build, npm run test)
• Frontend coverage meets 80% thresholds
• govulncheck ./... reports no known vulns
• npm audit --audit-level=high reports no known vulns
• Duplication budget (<2%) is respected
• Docs are updated as needed