mirror of
https://github.com/Llewellynvdm/nativefier.git
synced 2024-12-22 10:08:55 +00:00
HACKING.md: triage guidelines (PR #1338)
As discussed in https://github.com/nativefier/nativefier/issues/1258#issuecomment-1008522842 , here’s an attempt to formalize triage, 1. To agree on our triage practices. 2. To ease up recruiting more triagers. 3. To have a reference to point at when a user doesn't understand how we're triaging.
This commit is contained in:
parent
31fc580f1c
commit
088be2d258
71
HACKING.md
71
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/).
|
||||
|
Loading…
Reference in New Issue
Block a user