docs: make it easier to pick up a first contribution - #90
Merged
Conversation
The repo has three difficulty levels and a dozen area labels, and nothing said what any of them mean. A newcomer scanning the issue list could tell "good first issue" apart from the rest and nothing else, so the area labels read as noise and the levels were invisible. Says what each family is for and links the level filters directly, so picking an issue is one click rather than a guess.
The contributing section handed every visitor the same two links, so the answer to "where do I start" was three clicks away in another file. Names the entry points instead: the difficulty filter, and the fact that a rules contribution needs no Rust — which is the thing most people who want to help can actually do on day one.
Muawiya-contact
added
the
documentation
A rule is the one contribution that needs no toolchain and no Rust, and it's the contribution the project most needs — but both existing templates ask for a bug or a feature, so a rule arrived as free text and came back missing the path, the platform, or the reason the files regenerate. Asks for exactly what base.json needs, and for the one thing a reporter knows and we can't check: whether user data sits next to the cache. That is the Firefox-profile mistake in issue #40, and it's cheaper to ask than to discover after the rule ships.
"Contributing rules" ended on a four-step guide to writing the JSON, which reads as the price of entry. The knowledge is the scarce half — someone who knows where an app hides its cache can hand that over without touching the file at all.
Muawiya-contact
changed the title
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.
What & why
Three small docs changes, all aimed at the same gap: the project needs
rules and has beginner-sized issues, and neither was findable.
CONTRIBUTING.md— a "Picking an issue" section. The repo carriesthree difficulty levels (
level: beginner/intermediate/advanced) and a dozen area labels, and nothing said what any of themmean. Someone landing on the issue list could recognise
good first issueand nothing else. Now: what each level implies,direct links to the three filters, and a paragraph on what the area
labels are for.
README.md— name the entry points. The contributing sectionhanded every visitor the same two links. It now points at the beginner
filter and at the fact that a rules contribution needs no Rust.
Rules database entryissue template. A rule is the onecontribution that needs no toolchain, but both existing templates ask
for a bug or a feature, so a rule arrived as free text and came back
missing the path, the platform, or the reason the files regenerate. The
template asks for what
base.jsonneeds — and for the one thing onlythe reporter knows: whether user data sits next to the cache, which is
the Firefox-profile mistake from Firefox rule marks the whole profile folder as safe to remove #40.
docs/RULES.mdnow offers it asan alternative to writing the JSON yourself.
Docs and issue templates only; no code, no behaviour change.
Validation
git diff --checkclean.Checklist