Guidelines for submitting pull requests

This article should help you look like a pro when submitting a pull request to Tatoeba. Note that everything mentioned in this article are only guidelines and not rules. So don't worry, even if you failed to follow any of the points mentioned below, your pull request may still be accepted.

Understanding pull requests

This article will not cover in details what are pull requests. There are other articles and documentation out there that will explain it better than we can. Google is your friend, but here are some articles that may help:

• https://help.github.com/articles/using-pull-requests/
• https://guides.github.com/activities/contributing-to-open-source/#contributing
• http://www.thinkful.com/learn/github-pull-request-tutorial/#Using-Branches
• http://readwrite.com/2014/07/02/github-pull-request-etiquette

Steps summary

Here are the basic steps for creating a pull requests.

1. Create a branch (git checkout -b <branch_name>).
2. Modify the code.
3. Stage your modifications (git add <file>).
4. Create your commit (git commit -m "your message").
5. Push your branch (git push --set-upstream origin/<branch_name>).
6. Go to the list of branches in your forked repository and click on the "New pull request" button next to the desired branch.
7. Enter your title and description, then submit.
8. Once submitted, your pull request should appear in the Tatoeba/tatoeba2 pull requests.

Before you start working on a pull request

There's just one thing you have to do: let us know, because we would like to avoid that you start working on something that other people are already working on, or will be working on.

If your goal is to solve one of our issues, then post a quick comment on the issue to say "I'd like to work on this".

If you're going to work on something that you haven't found in our issues, contact us and explain the problem you'd like to solve.

Pull requests addressing a listed issue

1. About the branch name.

   • Name your branch based on the issue number: issue-{number} (e.g. issue-123).
   • This implies that you shouldn't try to make one pull request for several issues. Instead, make one pull request for each issue.
   • Your branch name can optionally contain some information about the topic of the pull request: issue-{number}_{topic-info} (e.g. issue-123_search-optimization).

2. About the title of your pull request.

   • If you are not inspired for a title, then you can re-use the same title as the issue you're addressing.
   • If you prefer to use your own custom title, please try to use a clear title.
   • Keep it below 150 characters if possible (100 characters is already a long title).
   • Don't mention the issue number you're trying to address. This information should be in the pull request description.

3. About the description of your pull request.

   • The first line of your description should be: This pull request addresses issue #{number}.. This alone can be enough for the description.
   • You may want to add a summary or some explanation about the changes and choices that you made.
   • We expect you to test your code locally before you commit. It can happen however that for some reason, you were not able to test something. If that is the case, please mention it in your description.

Pull requests addressing an unlisted issue

1. About the name of the branch.

   • You can name it as you want. Of course, preferably, it should have something to do with the problem you're trying to solve.
   • Use a dash (-) to separate words, e.g. search-optimization (rather than search_optimization or searchOptimization).

2. About the title of your pull request.

   • Try to use a clear title, not too vague.
   • Keep it below 150 characters if possible (100 characters is already a long title).

3. About the description of your pull request.

   • By submitting a pull request that does not address any documented issue, you are basically both submitting an issue and submitting a technical solution for it.
   • Therefore the first part of your description should explain the problem you're trying to solve. Read our Guidelines for submitting issues in order to have a better idea of what we expect to see there.
   • After explaining the problem, you may want to add a summary or some explanation about the changes and the choices that you made.
   • We expect you to test your code locally before you commit. It can happen however that for some reason, you were not able to test something. If that is the case, please mention it in your description.