GitHub Issues Etiquette

• May 3, 2022 - 17:28

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


  • When logging an issue is to observe general bug etiquette. 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!


Comments

As one who has contributed to some of this, first, I apologize. But also, I think we need to recognize that often there does need to be technical discussion regarding how to best solve an issue. And sometimes it takes time (and words) to work through that. So it's more a question of how to do have these discussions without making life harder for people just trying to implement solutions.

Sometimes I think it would be nice if there were a simple way to offload the discussions from the issue itself, and in the past we've sometimes re-directed such discussion to the forums. Especially if it felt necessary to get input from more users (eg, if we start speculating about which of two use cases is more commonly encountered).

But I think your last point, "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", is the key. And actually, with that in mind, keeping the discussion right there in the issue is useful, as it does allow the developer to see whether or not things seem settled.

So maybe something that would help is a tagging system that could help flag issues as "ready to be resolved based on the main description". In the original issue tracker, we used "active" versus "needs information" for this purpose at times. And we'd use the priority tags to help identify issues that hadn't really been looked at from ones we understand the important. But it was never consistent.

BTW, another observation about the basic problem here you are trying to address - it's kind of new for us. Not that we never had long drawn-out meandering discussions within issues before - you ain't seen nothin' yet :-). But normally, the people likely to be trying to fix the issues would be taking part in the discussion actively as well. So they'd have a finger don't the pulse of it all along, but it made for slower development. The way things are working now is incredibly efficient - I'm amazed at how quickly some things are getting done - but it does suggest a need for better organization to help keep things running so smoothly - which I guess means, more separation between the working out of the solutions and the actual implementation of them.

In reply to by Marc Sabatella

>So maybe something that would help is a tagging system that could help flag issues as "ready to be resolved based on the main description". In the original issue tracker, we used "active" versus "needs information" for this purpose at times. And we'd use the priority tags to help identify issues that hadn't really been looked at from ones we understand the important. But it was never consistent.

The OpenRA project (https://github.com/OpenRA/OpenRA) uses these tags: "PR: Unaddressed comment(s)", "PR: Fixup requested", "PR: Changes requested", "PR: Is Dependency", "PR: Rebase me!".

Maybe tags like this would be useful for us?

Do you still have an unanswered question? Please log in first to post your question.