Guidelines for submitting issues

At Tatoeba, we use the "Issues" in GitHub to keep track of bugs, enhancements, or feature requests. For anyone who wants to get involved in the evolution of Tatoeba, the issues are the place to go. They will give you an idea of the problems we are facing, and the problems we are working on. You can comment on issues to share your opinion or to bring your expertise to solve a certain problem. You can create new issues for bugs and enhancements that were not reported yet.

Everyone is free to create issues (you just need a GitHub account), but in order to avoid things becoming too chaotic, if you decide to create issues, please follow our guidelines.

Before submitting an issue

1. Create issues only when you have identified a specific problem that would require changes in Tatoeba's code. For everything else, use Tatoeba's Wall or contact us by email. For instance, if you have a question regarding how Tatoeba works, do not create an issue for it, but use the Wall or contact us by email.
2. If your have identified a security issue, contact us by email rather than creating an issue.
3. If you are rather new to Tatoeba, we recommend that you don't create issues in GitHub until you are more familiar with the project. Instead, submit your issues on Tatoeba's Wall and other people will report your issues into GitHub. We prefer that people who create new issues in GitHub are people who have a good knowledge and understanding of Tatoeba.
4. In order to avoid creating duplicate issues, take the time to search if there is already an existing issue that is similar to the one you want to create. To search issues, you can use the filter feature on the issues page. When searching issues, please take a look not only at open issues but also closed ones. The issue you want to submit may be something that we already discussed and decided to not implement.
5. In case you don't know how the GitHub issues work, you can read GitHub's documentation on the topic of "Managing projects". For instance to learn how to create an issue, you can read the article "Creating an issue".

Focus on describing the problem

When creating new issues, the main thing we would like you to remember is to focus on describing the problem, not the solution. You may not have all the knowledge to provide a good solution for a certain problem, and we do not expect you to. You are still very welcome to suggest one or several solutions for the problem, but providing the solution alone is not enough. We won't implement any solution without understanding the original problem.

More concretely:

• For bugs, tell us the steps to reproduce the bugs. Only after that, if you have a technical solution to solve the bug (i.e. you know what to change in our code), then you can suggest it.
• For enhancements, tell us first what annoys you with a certain feature. What are you trying to do, and cannot achieve efficiently, or cannot achieve at all? Only after you have explained what is wrong, you can suggest how things could be better.

Tips for writing good issues

The title

• Avoid vague titles. For instance "Strange bug" is not a good title. Try to be more specific, so that we have an idea of what the issue is about. For instance "Error when searching sentences with special characters" is a better title.
• Try to keep the title below ~150 characters. 100 characters is already a quite long title. We don't need to understand the whole problem from the title, we just need to have an overall idea of what it is about.
• Don't add meta information in the title. For instance, don't add things such as "Bug" or "Important" in the title. We have labels for that, and someone with the permission to label issues will add the relevant label(s) on your issues.

The description

• If you found a bug, describe step by step how to reproduce/find the bug. Describe it as if you were talking to someone who is completely new to Tatoeba, and want to explain to them what they would have to do to notice this bug.
• If the bug is a visual bug, take a screenshot of it, so that we can see how it looks like for you. Maybe it doesn't look the same for us.
• In general, give us as much detail as possible. For instance, if you tried to add a new sentence, and it didn't save properly, rather than simply saying "I tried to add a sentence and it didn't work", tell us exactly what was the sentence you tried to add.
• If you need to share a big chunk of code, or of text, you can use tools like bpaste.