Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
67 lines (50 loc) · 2.49 KB

CONTRIBUTING.md

File metadata and controls

67 lines (50 loc) · 2.49 KB
Raw

Contributing to BluePy

Thanks for your interest! BluePy is an honest alpha: we would rather ship a small set of trustworthy checks than a large set of unreliable ones. Please keep that bar in mind when contributing.

Development environment

BluePy uses uv and is pinned to Python 3.12.

uv python install 3.12
uv sync --extra dev            # minimal scan path + test/lint tooling
# add extras as needed for the area you touch:
uv sync --extra report --extra db --extra dev

Always run from the repository root (uv run …); the scanner imports src.* and reads relative config/rules.

Running tests

uv run pytest tests/unit tests/integration          # Docker-free
uv run pytest tests/acceptance/test_acceptance_logic.py
uv run python tests/acceptance/run_acceptance.py    # live, needs Docker/colima
  • GUI tests (tests/unit/test_gui_components.py) auto-skip unless the gui extra (PySide6) is installed.
  • Windows remediation tests need --extra windows (pywinrm).

Code style

  • Format with black and lint with ruff (line length 100): uv run black . and uv run ruff check ..
  • Type hints are expected on new functions.

How a check becomes "verified"

The default scan exposes only verified checks. To graduate a check from experimental to verified:

  1. The rule YAML lives under config/rules/<platform>/ and maps to a validator.
  2. The validator uses anchored matchers (e.g. exact tokens / structured parsing), not loose substring guesses.
  3. There are branch-covered causal tests asserting all three outcomes (PASS, FAIL, MANUAL) against realistic command output — see tests/acceptance/test_acceptance_logic.py for the pattern. Where feasible, include a one-time real command capture as a fixture.
  4. Set experimental: false in the rule YAML.
  5. For Linux, prefer adding live coverage to run_acceptance.py.

Checks that cannot meet this bar should stay experimental: true (the default) so they are excluded from the trusted scan.

Pull requests

  1. Open an issue to discuss non-trivial changes first.
  2. Keep PRs focused; update or add tests for behavior you change.
  3. Do not weaken the honesty invariants: no false-PASS validators, no exposing unverified checks by default, and keep the --json payload at its frozen 7-key shape.
  4. Ensure uv run pytest tests/unit tests/integration is green.

By contributing you agree your contributions are licensed under the project's MIT License.