Getting your GitHub Issue accepted
Discover more from BioDrop
Getting your GitHub Issue accepted
Are your Issues not getting accepted? Or are you thinking about raising an Issue for the first time?
As a project maintainer I’ve thought about the most common "Do Nots" that I come across when contributors raise an Issue in our Open Source project BioDrop, which prevent it from getting accepted. I want to give you my opinion as to how you can turn these into"Do's".
Read the Contributing Guide
Reading the Contributing Guide is the best place to start before you begin contributing to a project and raising an Issue, as it sets out what you need to do to contribute to the project.
It will typically explain how to report bugs, how to request enhancements as well as templates used on the project.
Project owners have spent time thinking through how they would like contributions to be made so the project runs smoothly, so they are more likely to accept an Issue which follows these guidelines.
Check the conversation
As a maintainer I have often had to close Issues because they are a duplicate or very similar to an already existing Issue.
I get it.. you have just thought of a great enhancement and you are keen for the project to have this. Before you raise the Issue, take some time to go through the existing Issue list to double check whether this has been raised or if there is a similar Issue. Who knows, you might be able to work on and collaborate on the existing Issue!
Don't try to solve everything in one Issue
Before you raise an Issue, think carefully about what it will contain.
If you are familiar with the BioDrop project then you might have seen that sometimes maintainers ask contributors to split their Issue into more than one.
You might spot more than one bug on the same webpage, so you are tempted to raise these bugs in the same Issue. But the likelihood is that these bugs affect different areas of code and may not be related, so should be raised as separate Issues. By doing so:
they can be triaged separately by the maintainers (for example, they may have different levels of priority of complexity);
they can be worked on by different people;
the higher priority bugs can be worked on sooner and shipped to the user quicker.
Having different elements with an Issue means that one section which is more complex, might be blocking and delaying another section which is more straightforward.
For the maintainers, it is easier to review if an Issue does not have multiple unrelated sections. Can you imagine how difficult it is for a maintainer to break down which sections are useful for the project and which ones are not...if they are all in one Issue?
Your Issue is more likely to be reviewed faster, accepted and ready for you to work on, if it focused.
It is easier to breakdown the items at this stage rather than at the pull request stage.
Title of the Issue
When you create a new Issue, if there are templates in the Repo you will be presented with a list of these to choose from. In BioDrop we have templates for "Bugs" and "Features" for example. By choosing the right template this means that the title of the Issue will start with the correct definition, like "Bug".
If you are contributing to an open source project that does not have these templates, then it is important to start off your title with what type the Issue relates to as this really helps maintainers with managing the project.
Other tips for a good title:
it should be short and concise - keep it to one line;
pay attention to the language and tone (but I will go into this below).
Spend time on the Description
If there is a template for the description of an Issue, this is a great place to start because the maintainers are likely to have included in the template the information that they are looking to see.
Writing a wall of text is hard for you to write and difficult for others to understand. Use markdown to emphasise any areas and break up the text into bullet points.
Remember, what makes sense to you might not make sense to someone else. Where possible add a screenshot identifying the bug you want to fix or even a screen recording if you can. This will help maintainers understand what you are trying to fix much more easily, and avoids having to ask for clarification - which can only delay in getting your Issue accepted.
When writing a description, just like the title to your Issue, it is important for you to think about the language and tone you use. Use words which can easily be understood - you may be dealing with a project which has contributions from all over the world and English may not be everyone’s first language. Also, use friendly language, such as "I have a suggestion", "What do you think about my idea...".
At BioDrop we do want to accept your Issue and I suspect that most maintainers of Open Source projects feel the same. We are extremely grateful that we are “powered by” the community and appreciate your time and insights. We do however want to make sure that contributions add value (this can be fixing a typo, so please do not be put off if you feel your contribution would be “small”) and are carefully considered.
We look forward to your contributions!
Sara