docs: the maintainer bot does not exist — say what is true, and ask for help - #25
Open
john-the-dev wants to merge 1 commit into
Open
docs: the maintainer bot does not exist — say what is true, and ask for help#25john-the-dev wants to merge 1 commit into
john-the-dev wants to merge 1 commit into
Conversation
…or help README, CONTRIBUTING and GRADING describe an automated maintainer that proposes entries, grades unrated ones and flags stale ones. There is no such bot: every commit is human-authored, validate.yml runs only on pull_request/push, and no app config exists under .github/. The costly line is GRADING.md's "the maintainer bot grades these on its next pass" — it tells a reader the 48 unrated entries are queued for automatic grading, so the repo's single largest contribution surface reads as taken. Replaces the five claims with what is true, and turns the gap into the ask: 48 of 59 entries are unrated, validate.mjs names every one, and grading one is the best first PR.
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
1 participant
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.
This PR takes one side of a fork that is yours to decide. Merging it is one answer; closing it is the other. Both are defensible and I have not assumed which you want.
What is true today
Measured, not inferred:
The repo description and README headline sell "continuously-maintained, quality-graded" with freshness + grading as the differentiator. A visitor who checks finds 81% unrated and no bot. For a stars goal that is the worst possible shape, because the claim attracts exactly the discerning reader who will check it.
The line that costs the most
GRADING.md: "unrated — Seeded or newly-added, not yet evidence-graded. The maintainer bot grades these on its next pass."That tells a would-be contributor the 48 unrated entries are already queued for automatic grading — so the repo's single largest contribution surface reads as taken.
scripts/validate.mjs:40has been printingunrated — needs first evidence-graded reviewfor all 48 the whole time. Visibility was never the problem; the docs were pointing people away from it.What this PR does
Replaces the five claims with what is true, and converts the gap into the ask — README now says grading an
unratedentry is the best first contribution, with the exact command that lists them. Validator still green:59 entries valid, 48 warning(s).The other fork, so you can pick with both in hand
Build the bot instead and make the docs true. Scoped honestly, it is not small: grading to the
Abar needs independent verification — specific CVEs/CVSS, named actors, dated confirmations. Lifting an entry's own prose into itsevidence[]would be circular, the entry justifying its own grade. So a real grading bot is a research agent with source access and a human review gate, not a formatter. A stale-flagger is genuinely small —last_verified > 90dis already computed byvalidate.mjs, so a scheduled workflow opening areview-neededissue is maybe 30 lines — but note zero of 59 entries are stale today (ages run 6–48 days against the repo's own 90-day rule), so it would ship with nothing to do.My read, offered as one input: the docs should match reality now regardless of whether the bot gets built, because the mismatch is live and public today and the bot is not. If you want the bot, this PR is still the right intermediate state — it just gets reverted when the bot lands.
If you'd rather I not touch the positioning copy at all, close this and I will leave it alone; nothing else depends on it.