Skip to content

docs: make CONTRIBUTING describe what the project actually does (closes #34, #30) - #36

Merged
snad1 merged 4 commits into
mainfrom
docs/contributing-accuracy
Jul 30, 2026
Merged

docs: make CONTRIBUTING describe what the project actually does (closes #34, #30)#36
snad1 merged 4 commits into
mainfrom
docs/contributing-accuracy

Conversation

@snad1

@snad1 snad1 commented Jul 30, 2026

Copy link
Copy Markdown
Contributor

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 than
assumed: no release-please-config.json, no .release-please-manifest.json, no commitlint
or .versionrc/.releaserc, and three workflows total — none of which publishes or bumps
anything. §3 now documents the real process: make version-set VERSION=x.y.z writes all
five declaration sites, the required version-consistency gate refuses a disagreement (or
a pyproject.toml that regrew a static version =), CHANGELOG.md is hand-written under
[Unreleased], and releases are hand-cut annotated tags with release-check as a
post-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_output for a wrapped external binary and opened with "copy the
template 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_command is documented as
what 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_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 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 cvss is optional on the model, so §4 says that is on the reviewer
instead 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 the
file CONTRIBUTING links to as the workflow of record. packages/adapters/README.md — the
doc QUICKSTART points at as the accurate contract — 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 supposed to be the authority for.

DoD gained two steps the project already required in practice but never wrote down:
updating docs/STATUS.md and adding a [Unreleased] changelog entry. Mirrored into the PR
template 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-set with no VERSIONusage: make version-set VERSION=x.y.z, exit 1.
  • assert_version_consistency.py on the clean tree → 0.1.1 consistently across 5 sites.
  • importlib.metadata.entry_points over all three groups → provx.adapters (5),
    provx.api_adapters (1), provx.active_api_adapters (3).
  • make help for the lint / test / accuracy targets replacing §5's prose tool list.
  • Every link target in the touched files resolves; the renamed §4 anchor was followed
    through in .github/ISSUE_TEMPLATE/new-adapter.yml and docs/QUICKSTART.md, which had
    said the recipe "predates the current contract".
  • assert_workflow_gating.test.sh, assert_workflow_gating.py, and
    assert_version_consistency.test.sh all pass locally — this PR touches .github/**, so
    workflow-gate runs.

Definition of Done

  • Safety — n/a, documentation only; no check, adapter, or egress path added.
  • Signal quality — n/a, no findings emitted.
  • Fixture test added — n/a, no adapter or parser changed.
  • Accuracy gate passes — n/a, no check or lab target touched (gate skips: no
    backend/adapters/lab path in the diff).
  • Docs / manifest updated — this PR is the doc update.
  • Plan-of-record updateddocs/STATUS.md: both deferral rows resolved in place,
    plus a new row for the remaining known drift.
  • Changelog[Unreleased] entry added.
  • Platform security — n/a, no secret or state-changing action involved.
  • DCO — every commit signed off.

Safety classification

  • passive (documentation only — no runtime behaviour changes)

snad1 added 3 commits July 30, 2026 16:02
…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>
@snad1
snad1 merged commit def26f8 into main Jul 30, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant