Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
145 lines (106 loc) · 6.49 KB

CONTRIBUTING.md

File metadata and controls

145 lines (106 loc) · 6.49 KB
Raw

Contributing To PEBRA

PEBRA accepts focused contributions that preserve its deterministic decision core, explicit trust boundaries, and testable CLI behavior.

The exhaustive command/session inventory is docs/PEBRA_COMMAND_REFERENCE.md. PEBRA commands are terminal-agnostic; examples below use PowerShell only where Windows executable or environment syntax differs, and the reference supplies Command Prompt and Bash/zsh equivalents.

Contribution Terms

PEBRA accepts contributions under the Apache License 2.0, without additional terms or conditions. Alternative terms require prior written agreement from a project maintainer. By submitting a contribution, you confirm that you have the right to submit it under the accepted terms.

Apache License 2.0 permits commercial use, modification, and redistribution subject to its terms. Do not submit code, data, generated artifacts, or other material that you do not have the right to license. Identify copied or adapted third-party material and preserve its required notices.

Development Setup

Use Python 3.11 or newer. A minimal Windows setup is:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\python.exe -m pip install pytest pytest-cov hypothesis syrupy jsonschema ruff import-linter nox textual-dev pytest-textual-snapshot==1.1.0

Use the equivalent activation and executable paths on macOS or Linux.

Run nox -s tests lint e2e-fast for the normal source checkout. Before release, run nox -s dev-package to build and verify the tracked source as a clean wheel and source distribution; use nox -s dev-package -- --open to open the installed wheel's dashboard.

External Engines

Prepare CodeGraph and inspect RCA readiness with:

pebra setup-engines --repo-root . --json

PEBRA installs its pinned CodeGraph build only from this explicit setup surface. It does not bundle RCA and never installs Rust, Cargo, or RCA automatically. If Cargo is missing, install Rust and Cargo with rustup, then install the exact accepted RCA revision:

cargo install --force --git https://github.com/mozilla/rust-code-analysis --rev 37e5d83c056c8cbf827223d5814a93c5218df1a9 --locked rust-code-analysis-cli

PEBRA_RCA_BIN may name the RCA launcher or its bin directory. For a binary managed outside Cargo, set PEBRA_RCA_SHA256 to its lowercase SHA-256 so PEBRA can bind trust to those exact bytes. Without accepted RCA, risk analysis still runs and maintainability benefit remains projected.

The real CodeGraph freshness lane is gated because it requires the external engine:

$env:E2E_CODEGRAPH = "1"
.\.venv\Scripts\python.exe -m pytest tests\integration\test_codegraph_freshness_real.py -q
Remove-Item Env:E2E_CODEGRAPH

Record this lane as not run when the engine is unavailable; default green tests do not imply it ran.

For an isolated synthetic Observatory, use python -m scripts.demo_observatory (TUI default), --dashboard, or --keep. This is a source-only developer module, not a root pebra command, and it must never use the checkout's .pebra/pebra.db.

Developing the Observatory TUI

pebra tui is a Textual surface. Launch the editable checkout directly from the repository root:

.\.venv\Scripts\pebra.exe tui --repo-root .

The equivalent module form is .\.venv\Scripts\python.exe -m pebra tui --repo-root .. For an explicitly bound read-only store, use --read-only --db path\to\pebra.db --repo-id <id> instead of --repo-root ..

For hot reload and the Textual dev console, run these in two terminals from the repository root:

# Terminal 1: Textual events and self.log(...) output
.\.venv\Scripts\textual.exe console

# Terminal 2: make the editable console script visible to Textual's child process
$env:PATH = "$PWD\.venv\Scripts;$env:PATH"
.\.venv\Scripts\textual.exe run --dev -c "pebra tui --repo-root ."

The --dev run hot-reloads pebra/tui/theme.tcss, and self.log(...) output routes to the console instead of corrupting the TUI. TUI diagnostics log identifiers, counts, timing, and error categories only — never source, tokens, candidate payloads, or sanction data (the TUI never handles those). After a deliberate visual change, regenerate the SVG baselines with .\.venv\Scripts\python.exe -m pytest tests\snapshots --snapshot-update and review them before committing.

Engineering Rules

  • Keep pebra.core deterministic and standard-library-only.
  • Respect the established core, application, port, adapter, composition, CLI, dashboard, and E2E boundaries. Import contracts enforce these relationships.
  • Exercise production behavior through real public surfaces where an end-to-end test is intended.
  • Do not weaken fail-closed behavior, candidate hash binding, approval binding, or audit-chain integrity to make a test pass.
  • Keep changes focused. Avoid unrelated refactors and generated metadata churn.
  • Add a regression test for every bug fix and focused coverage for new behavior.

Validation

Run the smallest relevant tests while developing, then the repository checks before requesting review:

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\ruff.exe check .
.\.venv\Scripts\lint-imports.exe
.\.venv\Scripts\python.exe -m pytest e2e\test_boundary_discipline.py -q

Some external-engine, browser, and paid-model lanes are gated. State clearly which gated checks were not run and why; never report them as passing without evidence.

Passing tests, review approval, a clean candidate, or an existing tag authorizes none of: creating or pushing a release tag, dispatching/rerunning a release workflow, approving a protected publication environment, publishing to an index, or creating a GitHub release. Each release mutation requires explicit maintainer authorization; follow RELEASING.md.

Pull Requests

  • Explain the user-visible or architectural problem and why the change is scoped correctly.
  • Include verification commands and results.
  • Call out behavior changes, trust-boundary changes, migration needs, and deferred work.
  • Keep commits reviewable and do not include local databases, credentials, paid-run artifacts, or unrelated experiment output.
  • Address review findings with tests when the finding describes a reproducible failure mode.

Security Reports

Follow SECURITY.md for suspected vulnerabilities. Do not open a public issue for an undisclosed security problem.