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 and sqlc generated- code drift checks, the strict documentation build, Docker Compose validation and Kubernetes rendering. 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, either web app, packages or their tooling changes.
  • Docs and contracts validation runs when documentation, contracts, Compose or Kubernetes inputs 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 when a maintainer records that documentation is unaffected.
  • The heavier container journey 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 the core-purity and adapter-isolation rules) and make check-boundaries, which fails if one service imports another service's Go packages. Generated integration types come from contracts/gen; the separate policy question for domain-free packages remains recorded in Software Structure. Architecture rules for human and AI contributors are summarized in the repository-root AGENTS.md.

Development prose follows the Documentation Style guide for status, terminology, evidence and diagram maintenance.

Work on a branch and open a pull request into main; do not push directly to main. Commit messages follow Conventional Commits. Use feat: and fix: only for user-facing changes. A maintainer-approved project-phase major version is permitted, but an incompatible contract change always needs an explicit decision record and migration path.

Node, Go, Python and installed dependency caches are reused between runs. The journey 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.