Contributing

Workflow

graph LR A[Create branch] --> B[Make changes] B --> C[Run make check] C --> D[Open pull request] D --> E[CI validates the change] E --> F[Review and merge]

Development setup

git clone git@github.com:Ready2Trace/PackyTrace.git
cd PackyTrace
make install

Before opening a pull request

make check

make check runs formatting checks, linters, unit tests, type checks, contract validation, the strict documentation build and Docker Compose validation. Run the slower full suite when changing containers or startup behavior:

make ci

GitHub Actions uses path-aware workflows so unrelated checks do not run:

  • Source CI runs only when services, the web app or their tooling changes.
  • Docs and contracts validation runs only when those files or Compose change.
  • Secret scanning runs on pull requests and pushes to main.
  • Docs Guard fails any pull request that introduces a feature (feat: title or commit) without changing documentation; the docs-exempt label overrides it deliberately.
  • The heavier container smoke test and the dependency vulnerability scan (make vuln-check: govulncheck plus npm audit) run every Monday and can be started manually from the Actions tab.

make lint runs golangci-lint (configured in .golangci.yml, including depguard rules that keep domain and application free of outer-layer imports) and make check-boundaries, which fails if any service imports another service's Go packages instead of the shared contracts. Architecture rules for human and AI contributors are summarized in the repository-root AGENTS.md.

Node, Go, Python and installed dependency caches are reused between runs. The smoke test reports container status and logs when startup fails. make secrets-check runs the same license-free Gitleaks scan used by CI.

Keep documentation current when behavior, architecture, or domain assumptions change. Generated build output and installed dependencies must not be committed.