From e378900f4310771912a1b36330b83f25459e91e6 Mon Sep 17 00:00:00 2001 From: Muawiya Amir Date: Sun, 6 Sep 2026 22:46:36 +0500 Subject: [PATCH 1/4] docs(contributing): explain the issue labels 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. --- CONTRIBUTING.md | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0254564..8ce65bb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -46,13 +46,36 @@ verdict levels and the safety reasoning are in [`crates/diskern-core/rules/base.json`](crates/diskern-core/rules/base.json), and adding one needs no Rust. -**Issues labelled `good first issue`** are scoped to a single file with -the reasoning already worked out. - **Documentation.** If something here or in `docs/` was wrong or missing when you followed it, that is a bug report worth filing even if you don't fix it. +### Picking an issue + +Open issues carry a difficulty label, so you can choose by how much of +the codebase you need to hold in your head at once: + +| Label | What it means | +| --- | --- | +| [`level: beginner`](https://github.com/Coding-Moves/diskern/issues?q=is%3Aopen+label%3A%22level%3A+beginner%22) | Scoped to one file, with the reasoning already worked out — a rule, a flag, a formatting fix. | +| [`level: intermediate`](https://github.com/Coding-Moves/diskern/issues?q=is%3Aopen+label%3A%22level%3A+intermediate%22) | Sits inside one crate and has to be tested against it — a stage in the report pipeline, a test harness. | +| [`level: advanced`](https://github.com/Coding-Moves/diskern/issues?q=is%3Aopen+label%3A%22level%3A+advanced%22) | Cross-cutting, or lands on a safety guarantee. Say what you're planning on the issue before you start. | + +Most `level: beginner` issues are also labelled +[`good first issue`](https://github.com/Coding-Moves/diskern/labels/good%20first%20issue); +[`help wanted`](https://github.com/Coding-Moves/diskern/labels/help%20wanted) +means we'd particularly like someone to take it. + +The rest of the labels say where a change lands rather than how hard it +is. `engine`, `cli` and `app` name the crate; `backend` and `frontend` +are the same split in broader terms; `rules`, `safety`, `ui/ux`, `ci`, +`testing`, `performance` and `documentation` name the concern. +`priority: high` means correctness or safety, not a deadline. + +Comment on the issue before you start, so two people don't write the +same patch. If nothing fits, opening an issue to describe what you want +to change is a fine first contribution on its own. + ## The loop 1. Fork, and branch from `main`. Branch names follow the commit prefixes From 27ac5a496a5b7f2eb508b3f2dcd720c92a7e6e0f Mon Sep 17 00:00:00 2001 From: Muawiya Amir Date: Sun, 6 Sep 2026 22:46:55 +0500 Subject: [PATCH 2/4] docs(readme): point newcomers at the beginner issues MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 64be34b..e855541 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,12 @@ Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for setup and guidelines, and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for how the pieces fit together. +Looking for somewhere to start? Issues are labelled by difficulty: +[`level: beginner`](https://github.com/Coding-Moves/diskern/issues?q=is%3Aopen+label%3A%22level%3A+beginner%22) +is scoped to a single file with the reasoning worked out, and teaching +Diskern about a cache on your platform is a +[rules change](docs/RULES.md) that needs no Rust at all. + ## License [MIT](LICENSE). Unless you explicitly state otherwise, any contribution From ca219bc737c4bac2aeb7cd9700899172fd9b5b5d Mon Sep 17 00:00:00 2001 From: Muawiya Amir Date: Sun, 6 Sep 2026 22:48:48 +0500 Subject: [PATCH 3/4] docs(issues): add a template for rules database entries MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .github/ISSUE_TEMPLATE/rule_request.md | 50 ++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/rule_request.md diff --git a/.github/ISSUE_TEMPLATE/rule_request.md b/.github/ISSUE_TEMPLATE/rule_request.md new file mode 100644 index 0000000..c1653f6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/rule_request.md @@ -0,0 +1,50 @@ +--- +name: Rules database entry +about: Tell us about a cache or artifact directory Diskern doesn't know yet +labels: rules, enhancement +--- + + + +**Which application, and on which OS?** + + + + +**Where does it keep the files?** + + + + +**What's in there, and what happens after it's removed?** + + + + +**Proposed verdict** + + + +- [ ] `safe` +- [ ] `review` +- [ ] not sure + +**Is there anything nearby that must NOT match?** + + + + +**Would you like to open the PR yourself?** + + From 029a3596a6465840de9af3efa065e8b6c21bf704 Mon Sep 17 00:00:00 2001 From: Muawiya Amir Date: Sun, 6 Sep 2026 22:49:02 +0500 Subject: [PATCH 4/4] docs(rules): offer the issue template as a way in MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "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. --- docs/RULES.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/RULES.md b/docs/RULES.md index 153143b..50e1949 100644 --- a/docs/RULES.md +++ b/docs/RULES.md @@ -95,3 +95,8 @@ rules PRs are very welcome. Guidelines: not), what happens after removal. 4. Add a test in [`rules.rs`](../crates/diskern-core/src/rules.rs) if the rule protects something critical. + +Don't want to write the JSON? Filing a +[rules database entry](https://github.com/Coding-Moves/diskern/issues/new?template=rule_request.md) +with the path and what regenerates it is just as useful — someone else +can turn it into a rule from there.