_I am the author and core maintainer of_ [_Quill_](http://beta.quilljs.com/) _— a powerful rich text editor, built with an API._

Many [open source](https://hackernoon.com/tagged/open-source) projects use [Github](https://hackernoon.com/tagged/github) Issues as the main medium of communication and tool for task management. Its openness and availability is one of their greatest strengths. But some quick tips will make you a much more responsible participant, especially in large projects.

### Reporting Issues

_Do_ open one Issue for one issue.

_Do_ open two Issues for two issues.

_Do_ **_not_** tack on “Oh by the way here’s another problem I noticed” to an unrelated Issue.

_Do_ keep facts and opinions separate, ideally facts first and opinions at the end. Facts include platform details, reproduction steps, and what you have tried. Opinions include speculations about root causes you have not investigated.

_Do_ be specific, especially in reproduction steps. Instead of the instruction: “type some text,” be unambiguously specific with the instruction: “Type ‘Test’”. The bug _might_ have to do with the shift key and it will not be reproduced by others repeatedly banging adsfasdfadsfasd. This is not a theoretical occurrence — underspecification remains one of the most common reasons valid issues get closed as not reproducible.

_Do_ reduce your reproduction steps to the minimal necessary to demonstrate your issue. It makes it easier for others to help you, and the culling often reveals relevant interactions.

_Do_ specify the platform or environment_,_ usually the browser and operating system. This matters a lot more than one would think.

_Do_ **_not_** include platforms that you have not tested on. It is enough to be a legitimate bug if only one supported platform is affected. False positives will only invite dismissal if others cannot reproduce on a platform you did not test on, yet included in the bug report.

_Do_ try to consistently reproduce your issue — in a clean environment. Start with the consistent part.

_Do_ report a recurring issue even without reproduction steps if you are unable to identify them, after an earnest effort. This is sometimes okay with enough details about the environment and context, for others to be able to help fill in the gaps.

_Do_ make use of bullets, colons, even incomplete clauses when appropriate. “Platform: Chrome/OSX, untested elsewhere” conveys just as much information as its grammatically correct equivalent.

_Do_ spend extra time writing a good title. It should be short, yet descriptive — similar to the approach of writing a good commit message. Contributors often view Issues in list view where only titles are shown and Issues with bad titles will get ignored.

_Do_ try to resolve or work around the issue, and provide details with what you tried, **even if it did not work**.

_Do_ answer other people’s questions if you know the answer. Responding to questions is not a privilege reserved for just maintainers. Earnestly helping others is what open source is about!

_Do_ **_not_** guess if you do not know the answer to someone’s question. Signals are helpful, not noise, wherever either comes from.

_Do_ follow the [issue template](https://github.com/blog/2111-issue-and-pull-request-templates) if one is provided.

### Requesting Features

_Do_ be specific in describing what you want to be added and how it would solve a problem you are facing.

_Do_ **_not_** open an Issue with just “make X better” or “improve X”.

_Do_ open an issue for a feature request with “Make X better by adding Y because Z”.

_Do_ propose an API spec, even if it has obvious shortcomings. This starts the conversation with concrete details, and progress can be made from there.

_Do_ not confuse feature size with project fit. Fit is determined first, then implementation. Some fitting features will take a long time to implement because they are large. But no unfit features should be implemented no matter how easy.

_Do_ **_not_** open hypothetical feature requests. If you do not personally need the feature or have the use case, you are not qualified to recommend the solution.

_Do_ use the [reaction feature](https://github.com/blog/2119-add-reactions-to-pull-requests-issues-and-comments), instead of commenting “+1” in 2016. A large group of open source maintainers almost [rage quit](https://github.com/dear-github/dear-github) over this and Github finally built it. Now use it!

_Do_ close feature requests you no longer need. If someone else has the same request, they can open a separate issue more focused on their needs.

### Pull Requests

_Do_ submit one pull request to address one issue.

_Do_ submit two pull request to address two issues.

_Do_ **_not_** tack on a minor whitespace or semicolon changes in unrelated commits or Pull Requests, even if the minor change is correct. Make a dedicated commit or Pull Request instead.

_Do_ read the [contributing.md](https://github.com/blog/2111-issue-and-pull-request-templates) guideline if one is linked.

_Do_ submit pull requests for typo fixes in documentation or comments. This is the easiest and most welcome way to get your name added to the contributor list.

_Do_ **_not_** submit a large surprise Pull Request. Discuss the need for it and the merits of your approach first, probably in a Github Issue or the project discussion forum or mailing list.

_Do_ **_not_** be surprised or get upset when you ignore the above and your Pull Request gets closed.

_Do_ **_not_** expect all Pull Requests to lead to being merged.

_Do_ **_not_** expect others to coach you through your Pull Request. It happens when time permits but expecting it is misguided entitlement. Pick an easier way to contribute if you get stuck.

_Do_ include tests with your Pull Request.

_Do_ follow the style guide if one is provided. If none is, use the existing codebase as a guideline.

_Do_ **_not_** confuse implementation cost with maintenance cost. The latter is far more expensive and healthy projects take long term considerations seriously.

### Being a Decent Human Being

_Do_ search through existing issues to see if yours has already been reported. It might even have already been resolved!

_Do_ flag other Issues as a duplicate. Sometimes it is hard to find the right search terms in Github Issues and duplicates get created despite best intentions.

_Do_ keep comments short, concise and on topic. High information density is essential for effective communication over a distributed and diverse landscape that is open source.

_Do_ read the documentation. No one wants to have to show their ugly side on a bad day. Also known as RTFM™.

_Do_ email the maintainers if you work for a giant company with an annoying legal department and will [abandon using the project](https://blog.powerdns.com/2014/05/05/how-to-talk-to-an-open-source-software-project-as-a-large-scale-or-otherwise-interesting-user/) without private assistance.

_Do_ not email the maintainers to draw attention to an issue you reported.

_Do_ enjoy the benefits of permissive open source software “free of charge… without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software…” guaranteed by the [license](https://opensource.org/licenses/MIT).

_Do_ **_not_** ignore the all caps part: “THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED…” Open source is largely a volunteer effort. Any additional help that volunteer contributors provide is additional.

_Do_ be charitable with your interpretation of others’ words. For example, reasonable interpretations of “What do you not understand?” include a condescending insult or hurried clarification attempt. But the most charitable interpretation is that it is an open ended invitation to be a data point used to improve the documentation. With global diversity of personalities and cultures participating in open source and the low emotional density of written text, always default to the most charitable interpretation of others’ words.

What are some of your dos and don’ts that I missed? Let me know in the comments or tweet [@jhchen](https://twitter.com/jhchen)!

_This post originally appeared on_ [_David Walsh_](https://davidwalsh.name/45-github-issues-dos-donts)_. Thanks to_ [_@avitaloliver_](https://twitter.com/avitaloliver)_,_ [_@shapiro_](https://twitter.com/Shapiro)_, and_ [_@timabbott_](https://github.com/timabbott) _for reviewing drafts of this post._

> [Hacker Noon](http://bit.ly/Hackernoon) is how hackers start their afternoons. We’re a part of the [@AMI](http://bit.ly/atAMIatAMI)family. We are now [accepting submissions](http://bit.ly/hackernoonsubmission) and happy to [discuss advertising &sponsorship](mailto:partners@amipublications.com) opportunities.

> To learn more, [read our about page](https://goo.gl/4ofytp), [like/message us on Facebook](http://bit.ly/HackernoonFB), or simply, [tweet/DM @HackerNoon.](https://goo.gl/k7XYbx)

> If you enjoyed this story, we recommend reading our [latest tech stories](http://bit.ly/hackernoonlatestt) and [trending tech stories](https://hackernoon.com/trending). Until next time, don’t take the realities of the world for granted!

Facebook

Twitter

Too Long; Didn't Read

Cassandra Forward a free Cassandra-focused community event

45 Github Issues Dos and Don’ts

Too Long; Didn't Read

Companies Mentioned

@jhchen

RELATED STORIES