docs: sync CONTRIBUTING.md with current process - #188
Merged
Conversation
Checked against docs/specs/researcher-process.md's current content, the actual schema version, and the real validation commands in scripts/ -- found four real points of drift, not just stale examples: - researcher field: said "Use your name or handle." This is the exact misattribution mistake researcher-process.md was written to prevent (defaulting to the PR author instead of the actual external primary source) -- caught and fixed on real published records this project has shipped (see researcher-process.md's AVE-2026-00060 worked example, and the AVE-2026-00070 correction). Rewrote to state the actual rule and point at the real doc. - owasp_asi/mitre_atlas/nist_ai_rmf: said "omit rather than force a poor fit." This is the literal bug found and fixed on AVE-2026-00078/79/80 (issue #178, #179): the corrected rule is always include the key, empty array when nothing fits -- an absent key and a documented empty array look the same in a diff but mean opposite things. - Step 3 validation: showed an ad-hoc inline Node/ajv snippet with no mention of the actual canonical tools this project runs, including in CI: scripts/validate_records.py, scripts/check_fixtures.py, pytest tests/. Replaced with the real commands. - Step 4/5: said detection-rule fixtures live in bawbel/scanner and a record "will not be merged" without one there, and told contributors to target `main`. Both wrong against actual current practice: the positive/negative fixtures scripts/check_fixtures.py enforces live in *this* repo's own tests/fixtures/ (confirmed by this project's own recent record PRs), and real record PRs target `develop`, not `main` -- main is only the GitHub default, not the integration branch. Corrected both, and added origin/develop to the git checkout examples so contributors don't branch from the wrong base and hit avoidable merge conflicts later. Each correction states what changed and why inline, not a silent rewrite, matching this project's standing practice for real corrections. Also audited good-first-issue labeling per the same task: only one issue has ever carried that label (#125, closed). Surveyed the full open backlog (12 issues) against it and found zero additional candidates that are both genuinely small AND have clear edges -- every open issue is either already resolved, explicitly blocked (#94, #126), an open design question with no stated resolution (#98, #105, #72, #160), a schema-version change requiring the project's own frozen- version discipline (#103, #104, #178), or requires the full add-ave-record research/scoring workflow (#150, the remaining item in #68), none of which are beginner-appropriate regardless of how small they sound. Not forcing labels onto issues that don't fit just to hit a number. Found and posted a real, useful side-finding instead: issue #68's original 8-item gap list is 7/8 stale, resolved by records shipped since it was opened; commented with the status so the backlog stays honest.
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.
Summary
Two-part task: (1) audit and expand
good first issuelabeling fromthe real backlog, (2) confirm
CONTRIBUTING.mdmatches the current,real process and fix any drift found.
Note on base branch: targets
develop, notmain— per this PR'sown fix (see below), that's now the stated, correct convention, so it
would be a little embarrassing for this specific PR to target
main.Part 1: good-first-issue audit — honest result, not a forced one
Real current state checked first: only #125 has ever carried the
label, and it's closed. Zero open coverage.
Surveyed the full open backlog (12 issues) for genuinely small,
low-risk, clear-edged candidates. Found zero that qualify, not for
lack of looking:
stated resolution (
#160's own title says "three questions") —exactly what a first issue should not be
project's own frozen-schema-version discipline; too consequential
for an unsupervised first contribution
full
add-ave-recordresearch/AIVSS-scoring/fixture workflow, theproject's most sensitive, expertise-gated task, regardless of how
well-scoped the underlying proposal is
Not forcing labels onto issues that don't fit the bar just to produce
a number. Real side-finding instead: #68's original 8-item gap
list turned out to be 7/8 stale — resolved by records shipped since it
opened (AVE-2026-00061/62/63/64/71/72/73). Posted the status
as a comment
rather than sit on it, left the issue open for the one real remaining
gap (sandbox-config weakening).
Part 2: CONTRIBUTING.md drift — four real corrections, not cosmetic
Checked against
docs/specs/researcher-process.md's current content,the actual schema, and the real scripts in
scripts/:researcherfield said "Use your name or handle" — the exactmisattribution mistake
researcher-process.mdexists to prevent,and one this project has actually shipped and had to correct (see
its
AVE-2026-00060worked example, and the realAVE-2026-00070fix). Corrected to state the real rule.
owasp_asi/mitre_atlas/nist_ai_rmfsaid "omit rather thanforce a poor fit" — the literal bug found and fixed on
AVE-2026-00078/79/80 (Schema v1.2.0: require owasp_asi, mitre_atlas, nist_ai_rmf keys to always exist (empty array allowed) #178, owasp_asi field: corpus and schema use fabricated ASI01-10 IDs, primary source uses T1-T17 #179). Corrected: always include the
key,
[]when nothing fits.mention of the actual canonical
scripts/validate_records.py/scripts/check_fixtures.py/pytest tests/. Replaced with thereal commands this project (and its CI) actually runs.
live in
bawbel/scannerand told contributors to targetmain.Both wrong against actual practice — fixtures live in this repo's
own
tests/fixtures/(check_fixtures.pyenforces it here), andreal record PRs target
develop. Corrected both, and addedorigin/developto thegit checkout -bexamples so a newcontributor doesn't branch from the wrong base and hit an avoidable
merge conflict later (this exact class of conflict happened for
real, separately, this same day).
Every correction states what changed and why inline — no silent
rewrites.
Checklist
considered came from the real, existing backlog
CONTRIBUTING.mdchecked against real, current files, notmemory
python3 scripts/validate_records.py(80/80),pytest tests/(339 passed) — unaffected doc-only change, confirmed anyway