GitHub Issues Etiquette

As we get closer to our second alpha, I thought I'd write this quick guideline to help us discuss and resolve issues on GitHub more effectively.

In general, the process and general atmosphere on the MuseScore GitHub issues is quite good. However, it has been mentioned to me by numerous people in the community and also the internal team that the experience of trying to solve or understand issues can sometimes be quite mentally exhausting.

In the last week, I have specifically been going through our backlog of issues in order to reduce the cognitive load on our development team and based on that experience, have put together a few guidelines for logging issues or contributing to discussions on them. Please feel free to offer feedback on these guidelines in the comments and if there's a broad consensus, I'll update them here.

TL/DR: empathise with the developer who would like to solve the issue and don't make their head spin

• Do not log multiple bugs or feature requests in one issue

• If logging a bug, make sure it can be reproduced to avoid forcing others to have to spend time trying to find it for themselves

• Only include relevant information related to the issue in question. For example, don't add asides about other things that are not working or features you would like to see. Discourage others from doing this in the comments section.

• Avoid really complex text descriptions in favour of visuals and video, which often do a much better job of communicating clearly. Basically, if you find yourself writing something like '...when I roll my mouse over a note in voice two, the inspector automatically scrolls down...' - use screen capture!

• Only comment on the issue at hand. Ideally, don't comment unless you have context to add or an idea for a solution.

• Try to minimise the amount of comments that you make and try to keep them as short as possible. Think of the developer who'll be reading through all the comments to figure out what to do. If there are dozens of lengthy back and forths, they may (and often do) conclude that they don't know how to resolve the bug and this then requires more time to be spent for us (the internal team) to re-explain the issue.

• Make sure the main issue description is updated to reflect consensus reached in the comments section. A developer trying to fix an issue should be able to do so without needing to read through all the comments

--

You'll notice no points about being nice and polite... because everyone is lovely. This is really all about trying to solve issues more quickly.

Thanks a lot!