docs: make CONTRIBUTING describe what the project actually does (closes #34, #30) - #36
Merged
Conversation
…r built CONTRIBUTING §1 claimed Conventional Commits "drives the automated changelog and version bumps" and §3's flow ended "auto changelog + version -> next release". None of that machinery exists: there is no release-please config, no commitlint, and no publish workflow of any kind. §1 now states the commit prefixes as the human-readability convention they are. §3 gains a "Versioning and releases" subsection describing what actually runs: contributors never touch a version, a maintainer bumps with `make version-set VERSION=x.y.z` (all five declaration sites at once), the required `version-consistency` gate refuses a disagreement or a pyproject that regrew a static version, CHANGELOG.md is hand-written under [Unreleased], and releases are hand-cut tags with `release-check` as a post-hoc detector rather than a gate. Automating this is named as a future item, not implied as present. PROJECT_SETUP_PLAYBOOK §B1 and its §B2 flow diagram carried the same claim verbatim, in the file CONTRIBUTING links to as the workflow of record; both corrected, along with the repository-layout row asserting a release workflow. The Definition of Done gains the two steps the project already required in practice but never wrote down: updating docs/STATUS.md and adding a CHANGELOG [Unreleased] entry. Mirrored into the PR template so the two cannot drift. Closes #34 Signed-off-by: Solomon Nii Amu Darku <snad1@users.noreply.github.com>
CONTRIBUTING §4 walked `build_command` / `parse_output` for a wrapped external binary and opened by telling contributors to "copy the template adapter" - a template that does not exist. The shipped contract is `probe()` across three protocols in provx_sdk.plugins. §4 now covers: picking one of ToolAdapter / ApiAdapter / ActiveApiAdapter by unit of work; the manifest, noting the safety gate treats anything not exactly "passive" as intrusive so the classification fails closed; implementing probe through fetch_within_scope and nothing else (PX-EGRESS, PX-SCOPE); a pure parse_output returning FindingDraft (PX-DETERMINISM, PX-FIXTURE); the entry-point line; the fixture pair; and the lab positive/clean pair. `build_command` is documented as what it is - the subprocess path for copyleft tools (PX-LICENSE), with exactly one of the two live per adapter - not deleted. Two things the old recipe never said and a contributor could not infer: Evidence.matched_rule gets its own step because the accuracy harness keys on it and raises without it, and the lab manifest's `adapter:` key silently defaults to security_headers if omitted. The three hand-maintained wiring lists (compose services + depends_on, the Makefile up -d list, a --adapter run line) are called out, because nothing derives them from the entry points and an adapter can ship, pass its unit tests, and never be scored. Honest about enforcement: PX-ATTACK's technique ID is format-validated but its presence is not, and cvss is optional on the model, so §4 says that is on the reviewer rather than implying CI catches it. packages/adapters/README.md was itself still calling the SDK "scaffolding", documenting build_command as the contract, omitting ActiveApiAdapter entirely, and pointing circularly back at the §4 it was meant to be the authority for. Contract sections corrected, subtype table extended to three, and "Adding an adapter" now names shipped adapters to start from instead of a template. §5 replaces the prose tool list with the real targets (make lint / test / accuracy). The renamed §4 heading is followed through in the new-adapter issue form and QUICKSTART, which had said the recipe "predates the current contract". Closes #30 Signed-off-by: Solomon Nii Amu Darku <snad1@users.noreply.github.com>
Both deferrals this branch closes were tracked here with explicit land-with conditions, so they are resolved in place rather than deleted: the §4 cookbook row in ## Documentation (issue #30) and the §1/§3 automation row in ## Versioning (issue #34, whose land-with was "the issue filed alongside this PR"). The §4 row is honest that it did not wait for its stated condition - the next adapter PR - because the same pass was already correcting the neighbouring sections. Adds a row for the remaining known doc drift rather than leaving it implicit: the SDK README's stale layout tree, lab/README's "six adapters / twelve targets" against nine and fourteen, and PROJECT_SETUP_PLAYBOOK's release cadence section, which was left because it reads as a plan rather than a claim about shipped machinery. The CHANGELOG entry is the first written under the DoD step this branch adds. Refs #34, #30 Signed-off-by: Solomon Nii Amu Darku <snad1@users.noreply.github.com>
§3 closed by sending a contributor to #34 to discuss building release automation. #34 is the defect that CONTRIBUTING *described* automation as already existing - a bug this branch closes. Pointing forward-looking work at a closed bug asks a contributor to reopen a defect in order to propose a feature, and the reference rots the moment #34 closes. Filed #38 as the honest home for the want, carrying the constraints any solution inherits from #31 (one version for the whole product, each package buildable from its own directory with no .git, deterministic, air-gap-safe) so they are not rediscovered. §3 now points there; STATUS names it so the plan-of-record tracks an open item rather than an unnumbered intention. Refs #38 Signed-off-by: Solomon Nii Amu Darku <snad1@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
CONTRIBUTING described a project this is not. Two tracked issues, both closed here.
§1/§3 promised release automation that was never built (#34). "Conventional Commits …
drives the automated changelog and version bumps", and the flow diagram ended
→ auto changelog + version → next release. Re-verified against the tree rather thanassumed: no
release-please-config.json, no.release-please-manifest.json, no commitlintor
.versionrc/.releaserc, and three workflows total — none of which publishes or bumpsanything. §3 now documents the real process:
make version-set VERSION=x.y.zwrites allfive declaration sites, the required
version-consistencygate refuses a disagreement (ora
pyproject.tomlthat regrew a staticversion =),CHANGELOG.mdis hand-written under[Unreleased], and releases are hand-cut annotated tags withrelease-checkas apost-hoc detector, not a gate. Automation is named as a future item — not implied as
present, which is the distinction the STATUS row existed to protect.
§4's adapter cookbook predated the shipped contract (#30). It walked
build_command/parse_outputfor a wrapped external binary and opened with "copy thetemplate adapter" — a template that does not exist. Rewritten to the shipped
probe()contract across all three protocols, plus the two things a new adapter needs to actually be
scored: the fixture pair and the lab positive/clean pair.
build_commandis documented aswhat it is — the subprocess path for copyleft tools (PX-LICENSE), exactly one of the two
live per adapter — rather than deleted.
Two things the old recipe never said and a contributor could not infer:
Evidence.matched_rulegets its own step because the accuracy harness keys on it and raiseswithout it, and the lab manifest's
adapter:key silently defaults tosecurity_headersif omitted. The three hand-maintained wiring lists (compose services +
depends_on, theMakefile
up -dlist, a--adapterrun line) are written down as the sharp edge they are:nothing derives them from the entry points, so an adapter can ship, pass its unit tests, and
never be scored at all.
Honest about enforcement too — PX-ATTACK's technique ID is format-validated but its
presence is not, and
cvssis optional on the model, so §4 says that is on the reviewerinstead of implying CI catches it.
Also corrected where the same falsehood had propagated.
docs/PROJECT_SETUP_PLAYBOOK.md§B1 and its §B2 flow diagram carried it verbatim, in thefile CONTRIBUTING links to as the workflow of record.
packages/adapters/README.md— thedoc QUICKSTART points at as the accurate contract — was itself still calling the SDK
"scaffolding", documenting
build_commandas the contract, omittingActiveApiAdapterentirely, and pointing circularly back at the §4 it was supposed to be the authority for.
DoD gained two steps the project already required in practice but never wrote down:
updating
docs/STATUS.mdand adding a[Unreleased]changelog entry. Mirrored into the PRtemplate so the two cannot drift. This PR is the first to obey the changelog step.
No product code changed. No release automation was built.
Closes #34
Closes #30
Verification
Every command and path in the new text was executed or read out of the tree before being
written, not paraphrased from the docs it replaces:
make version-setwith noVERSION→usage: make version-set VERSION=x.y.z, exit 1.assert_version_consistency.pyon the clean tree →0.1.1 consistently across 5 sites.importlib.metadata.entry_pointsover all three groups →provx.adapters(5),provx.api_adapters(1),provx.active_api_adapters(3).make helpfor thelint/test/accuracytargets replacing §5's prose tool list.through in
.github/ISSUE_TEMPLATE/new-adapter.ymlanddocs/QUICKSTART.md, which hadsaid the recipe "predates the current contract".
assert_workflow_gating.test.sh,assert_workflow_gating.py, andassert_version_consistency.test.shall pass locally — this PR touches.github/**, soworkflow-gateruns.Definition of Done
backend/adapters/labpath in the diff).docs/STATUS.md: both deferral rows resolved in place,plus a new row for the remaining known drift.
[Unreleased]entry added.Safety classification
passive(documentation only — no runtime behaviour changes)