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:
Ronan Jouchet 2022-01-31 16:23:47 -05:00 committed by GitHub
parent 31fc580f1c
commit 088be2d258
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 71 additions and 0 deletions

View File

@ -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**.
Its 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 isnt reproducible (e.g. a non-trivial bug
happening on an internal site), express that we cant 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`.
Its 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 whats `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 were 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 theres 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, youll 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. **Dont scold authors of lame "+1" comments**, this only adds to the noise
youre 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. Were not there yet, so “hidden as off-topic” will do.
10. **Dont 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/).