Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
135 lines (90 loc) · 5.08 KB

CONTRIBUTING.md

File metadata and controls

135 lines (90 loc) · 5.08 KB

Contributing to Sovereign Map

Thanks for contributing.

Quick Start for New Contributors

After cloning, run the onboarding-safe baseline checks:

If you want starter tasks, browse labels:

  • good first issue
  • help wanted
  • documentation
  • observability

Pull Request Checklist

Before opening or merging a PR, confirm all items below:

Use the repository PR template at .github/pull_request_template.md when opening PRs.

  • CI workflows pass on your branch
  • Cross-platform lanes are green for relevant changes (Build and Test, Windows Client EXE Build, macOS Client Smoke)
  • Security checks pass (including CodeQL)
  • Documentation is updated for any behavior/config changes
  • Documentation sync completed when workflows, tests, or security defaults changed
  • No secrets or credentials are committed

Pinned Lint and Validation Guardrails

To avoid recurring CI failures and match GitHub Actions behavior locally, run these checks before pushing:

  • make quickstart-verify
  • make lint-soft
  • make alerts-test
  • python3 -m black --check .
  • ./.venv/bin/python tests/scripts/python/run_full_validation_suite.py --profile deep

Notes:

  • The Lint Code Base workflow enforces PYTHON_BLACK. Treat Black failures as merge-blocking.
  • If make lint-soft fails due local TOOLROOT mismatch, rerun with make lint-soft TOOLROOT=$(go env GOROOT).
  • The full validation suite now uses the invoking interpreter (sys.executable) for Python checks. Prefer running it from ./.venv/bin/python to avoid dependency drift.

Documentation Sync Requirements

For changes that affect runtime APIs, auth, trust, or deployment defaults, documentation updates are mandatory in the same PR.

Minimum required files to update:

  • README.md for user-facing behavior, endpoints, headers, and env vars
  • Documentation/Project/ROADMAP.md for milestone status and next steps
  • Any affected deployment/testing guide under Documentation/

Examples of changes that require doc sync:

  • New/changed HTTP endpoints or request/response fields
  • New/changed auth modes, token locations, or role checks
  • New/changed environment variables or compose overlays
  • New test harnesses or validation flows used for release confidence

Definition of Done for API/Security PRs

A PR touching proof verification, hybrid verification, ledger, TPM trust, or transport security should include:

  • Unit tests for happy-path and at least one negative path
  • Integration coverage where route registration or middleware behavior changed
  • README endpoint and auth examples aligned with the implementation
  • Roadmap status update indicating whether the change is completed or follow-up work remains

Contributor Rankings & Reward Points

The repository includes a Git-based reward scoring system to rank contributions.

  • Run make contributors-rankings
  • Outputs:
    • test-results/contributor-rankings/CONTRIBUTOR_RANKINGS.md
    • test-results/contributor-rankings/contributor_rankings.json

Current points formula:

  • points = commits*5 + additions*0.05 + deletions*0.02 + files_touched*0.5

Default scoring window is the last 30 days. You can customize window and output paths with:

  • python3 scripts/contributor_rankings.py --since "90 days ago" --until "now" --top 50

CodeQL Guardrail (Temporary)

This repository uses an advanced CodeQL workflow at .github/workflows/codeql-analysis.yml.

  • Do not enable GitHub CodeQL Default Setup for this repository.
  • Enabling Default Setup can trigger Java/Kotlin analysis on mobile-apps/ and fail with build-mode: none.
  • If this happens, disable Default Setup in Security → Code scanning and re-run the advanced workflow.

For details, see .github/CODEQL.md.

Recommended Branch Protection

For main, enable branch protection with:

  • Require pull requests before merge
  • Require status checks to pass before merge
  • Require branches to be up to date before merge

At minimum, require these checks:

  • CodeQL Security Analysis / Analyze Code (go)
  • CodeQL Security Analysis / Analyze Code (javascript-typescript)
  • CodeQL Security Analysis / Analyze Code (python)
  • Reproducibility Check / Clone Reproducibility
  • Workflow Action Pin Check / Enforce SHA-Pinned Actions
  • Governance Check / Governance Integrity
  • Build and Test / build
  • Windows Client EXE Build / Build Windows Client EXE
  • macOS Client Smoke / macOS Client Smoke
  • Observability CI / Validate Dashboard Queries
  • docs-markdownlint / markdownlint
  • Docs Quality / markdown-lint-and-links
  • Docs Pages / deploy

Branch protection alignment rule:

  • If a workflow or job name is renamed, update required checks in repository settings in the same change window. Stale required check names can block merges even when CI is healthy.

Repository Settings (Admin Only)

Metadata updates for description, homepage, and topics require repository admin permissions. Use:

  • Runbook: Documentation/Project/REPO_SETTINGS_ADMIN_RUNBOOK.md
  • Fallback helper: scripts/repo_settings_fallback.sh