diff --git a/HACKING.md b/HACKING.md index fc6c9a6..53bb5b1 100644 --- a/HACKING.md +++ b/HACKING.md @@ -180,3 +180,74 @@ npm run changelog -- $VERSION Do follow semantic versioning, and give visibility to breaking changes in release notes by prefixing their line with **[BREAKING]**. + +### Triage + +These are the guidelines we (try to) follow when triaging [issues](https://github.com/nativefier/nativefier/issues): + +1. Do your best to conciliate **empathy & efficiency, and keep your cool**. + It’s not always easy 😄😬😭🤬. Get away from triaging if you feel grouchy. + +2. **Rename** issues. Most issues are badly named, with titles ranging from + unclear to flat out wrong. A good backlog is a backlog of issues with clear + concise titles, understandable with only the title after you read them once. + Rename and clarify. + +3. **Ask for clarification & details** when needed, and add a `need-info` label. + + 1. In particular, if the issue isn’t reproducible (e.g. a non-trivial bug + happening on an internal site), express that we can’t work without a + repro scenario, and flag as `need-info`. + +4. **Label** issues with _category/sorting_ labels (e.g. `mac` / `linux` / `windows`, + `bug` / `feature-request` ...) and _status_ labels (e.g. `upstream`, `wontfix`, + `need-info`, `cannot-reproduce`). + +5. **Close if needed, but not too much**. We _do_ want to close what deserves it, + but closing _too_ ruthlessly frustrates and disappoints users, and does us a + disservice of not having a clear honest backlog available to us & users. So, + + 1. When in doubt, leave issues open and triaged as `bug` / `feature-request`. + It’s okay, reaching 0 open issues is _not_ an objective. Or if it is, + it deserves to be a development objective, not a triage one. + 2. That being said, do close what’s `upstream`, with a kind message. + 3. Also do close bugs that have been `need-info` or `cannot-reproduce` for + too long (weeks / months), with a kind message explaining we’re okay to + re-open if the requested info / scenario is provided. + 4. Finally, carefully close issues we do not want to address, e.g. requests + going against project goals, or bugs & feature requests that are so niche + or far-fetched that there’s zero chance of ever seeing them addressed. + But if in doubt, remain at point 1. above: leave open, renamed, labelled. + +6. **Close duplicates issues** and link to the original issue. + + 1. To be able to notice dups implies you must know the backlog (one more + reason to keep it tidy and palatable). Once in a blue moon, do a + "full pass" of the whole backlog from beginning to end, you’ll often + find lots of now-irrelevant bugs, and duplicates. + +7. **Use [GitHub saved replies](https://github.com/settings/replies)** to + automate asking for info and being nice on closing as noanswer / stale-needinfo. + +8. **Transform findings stemming from issues discussion** into documentation + (chiefly, [CATALOG.md](CATALOG.md) & [API.md](API.md)), or into code comments. + +9. **Don’t scold authors of lame "+1" comments**, this only adds to the noise + you’re trying to avoid. Instead, hide useless comments as `Off-topic`. + From personal experience, users do understand this signal, and such hidden + comments do avoid an avalanche of extra "+1" comments. + + 1. There are shades of lame. A literal `"+1"` comment is frankly useless and + is worth hiding. But a comment like `"same for me on Windows"` at least + brings an extra bit of information, so can remain visible. + + 2. In a perfect world, GitHub would let us add a note when hiding comments to + express _"Please use a 👍 reaction on the issue to vote for it instead of_ + _posting a +1 comment"_. In a perfecter world, GitHub would use their AI + skillz to automatically detect such comments, discourage them and nudge + towards a 👍 reaction. We’re not there yet, so “hidden as off-topic” will do. + +10. **Don’t let yourself be abused** by abrasive / entitled users. There are + plenty of articles documenting open-source burnout and trolls-induced misery. + Find an article that speaks to you, and point problematic users to it. + I like [Brett Cannon - The social contract of open source](https://snarky.ca/the-social-contract-of-open-source/).