Skip to content

docs: sync CONTRIBUTING.md with current process - #188

Merged
chaksaray merged 1 commit into
developfrom
docs/contributor-barrier-lowering
Aug 15, 2026
Merged

docs: sync CONTRIBUTING.md with current process#188
chaksaray merged 1 commit into
developfrom
docs/contributor-barrier-lowering

Conversation

@chaksaray

Copy link
Copy Markdown
Contributor

Summary

Two-part task: (1) audit and expand good first issue labeling from
the real backlog, (2) confirm CONTRIBUTING.md matches the current,
real process and fix any drift found.

Note on base branch: targets develop, not main — per this PR's
own 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:

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/:

  1. researcher field said "Use your name or handle" — the exact
    misattribution mistake researcher-process.md exists to prevent,
    and one this project has actually shipped and had to correct (see
    its AVE-2026-00060 worked example, and the real AVE-2026-00070
    fix). Corrected to state the real rule.
  2. owasp_asi/mitre_atlas/nist_ai_rmf said "omit rather than
    force 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.
  3. Validation commands showed an ad-hoc Node/ajv snippet, no
    mention of the actual canonical scripts/validate_records.py /
    scripts/check_fixtures.py / pytest tests/. Replaced with the
    real commands this project (and its CI) actually runs.
  4. Fixture location + PR base branch: said detection-rule fixtures
    live in bawbel/scanner and told contributors to target main.
    Both wrong against actual practice — fixtures live in this repo's
    own tests/fixtures/ (check_fixtures.py enforces it here), and
    real record PRs target develop. Corrected both, and added
    origin/develop to the git checkout -b examples so a new
    contributor 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

  • Confirmed real current label counts before assuming
  • No new tasks invented — every good-first-issue candidate
    considered came from the real, existing backlog
  • CONTRIBUTING.md checked against real, current files, not
    memory
  • Real corrections get a visible note, not a silent overwrite
  • python3 scripts/validate_records.py (80/80), pytest tests/
    (339 passed) — unaffected doc-only change, confirmed anyway

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.
@chaksaray
chaksaray merged commit 37c91c7 into develop Aug 15, 2026
6 checks passed
@chaksaray
chaksaray deleted the docs/contributor-barrier-lowering branch August 15, 2026 01:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant