Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
84 lines (59 loc) · 2.52 KB

CONTRIBUTING.md

File metadata and controls

84 lines (59 loc) · 2.52 KB

Contributing to pipelock-verify

Thanks for your interest.

This package is the Python reference verifier for Pipelock action receipts. The core rule: this implementation must match the Go reference byte-for-byte. Any change that causes verifier divergence needs coordination with the Go side before it lands.

Prerequisites

  • Python 3.9+
  • pip

Quick Start

git clone https://github.com/luckyPipewrench/pipelock-verify-python
cd pipelock-verify-python
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

Development Workflow

  1. Fork the repository on GitHub.
  2. Clone your fork and create a feature branch.
  3. Make changes with tests.
  4. Run the pre-commit checklist below.
  5. Open a PR against main.

Branch naming:

  • feat/ for new features
  • fix/ for bug fixes
  • chore/ for maintenance
  • docs/ for documentation

Pre-Commit Checklist

All four must pass with zero issues. These match what CI runs.

pytest                                          # full test suite + conformance
ruff check pipelock_verify tests                # lint
ruff format --check pipelock_verify tests       # format check
mypy pipelock_verify                            # strict type check

Conformance Rule

The tests/conformance/ directory holds golden files generated by the Go reference. When the Go side regenerates them, the Python side must still verify every one successfully.

To refresh conformance fixtures from a local Pipelock checkout:

cd /path/to/pipelock
go test ./sdk/conformance/ -run TestGenerateGoldenFiles -update
cp sdk/conformance/testdata/*.{json,jsonl} \
   /path/to/pipelock-verify-python/tests/conformance/
pytest

A Python change that causes a conformance fixture to fail is a bug. Fix the Python side. Do not edit the fixture.

What Needs Cross-Implementation Coordination

  • Changes to canonicalization rules (the SHA-256 signing input format)
  • Changes to the receipt schema fields
  • Changes to action type enum membership
  • Changes to chain linkage rules (chain_prev_hash, chain_seq, genesis handling)

For any of those, open an issue in the Go repo first, reach consensus, ship both sides together.

What Can Land Independently

  • New tests, including regression tests for bugs you find
  • Doc improvements
  • Type annotation improvements
  • Performance improvements that do not change the verification result
  • Python packaging, CI, and tooling changes

Reporting Security Issues

See SECURITY.md.