Issue Guidelines

Before opening up an issue, please read the following guidelines first.

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. 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. This matters a lot more than one would think.
• Do specify your python environment in particular. Post the output of python --version, don't speculate. Your system possibly has multiple python version installed, make sure you are using the intended version.
• 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: OSX 10.14, 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. Titles such as "Help me fix!!" or "Cant run module .." are extremely bad examples. Contributors often view Issues in list view where only titles are shown and Issues with bad titles might 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.

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 a code spec, even if it has obvious shortcomings. For example, "Add function F that accepts variables x,y and returns True or False". 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 instead of commenting “+1” or "I agree i want this too". A large group of open source maintainers almost rage quit 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.