Version at: 29/06/2013, 17:38
# The ultimate guide for Tatoeba developers Somehow you've stumbled upon Tatoeba, somehow you've found the project really interesting, and somehow you decided to help us maintain and improve Tatoeba. But you're not sure exactly what you can do. This article is here to explain whatever you need to know to actually get things done. Note that this guide only applies to people who want to help with the current version of Tatoeba and for a substantial period of time. If you want to help for a shorter period of time, you can get the information you need here as well, but you don’t have to follow all the steps. ## Getting started ### Step 1 - Let us know Send us an email to team@tatoeba.org to inform us that you would like to help. Tell us when you discovered Tatoeba, your username on Tatoeba (if you have an account), how much experience you have in web development, how much time you think you can dedicate to Tatoeba, when you are usually available, and whether there is something specific you really want to work on. ### Step 2 - Take a look at the tickets We use a platform called Assembla to host the current source code. This platform has a [ticket system](https://www.assembla.com/spaces/tatoeba2/tickets), and this is where we will define all the tasks. This will give you a more precise idea of what needs to be done, and from there you can start deciding what you’d want to work on. You need to know that the code has not evolved much between July 2011 and April 2013 (so for pretty much two years), nor have the tickets. Some tickets may be outdated, some may be unclear, some may have been already solved but not closed. Trang is still in the process of cleaning, completing and reorganizing them. Look at the date when the ticket was created. If it was created after April 2013, it’s a valid one for sure. If the date is much older, then it may not be valid anymore. ### Step 3 - Install Tatoeba on your machine It’s all explained [here](http://en.wiki.tatoeba.org/articles/show/install-tatoeba-php). It can be practical for you to be on IRC while doing this (server: freenode, channel: #tatoeba). If you get stuck somewhere, other people in the channel can help you out. ### Step 4 - Your first commit In order to commit anything, you will need to be in the project team on Assembla. So you will need to [create an account](https://www.assembla.com/plans) there (just a free account), and tell Trang your username so I can invite you to the project team. You will then be given a very small task to do, so that you can make sure you are able to commit. Each commit should ideally refer to one ticket. This will be true of your first commit. Sometimes a commit may refer to no ticket, or to two tickets, but this should be exceptional. In order to refer to a ticket, you need to write in the comment for the commit “re #ticketNumber” (for instance: re #373). This way, the commit will appear in the ticket comments (cf. [comments for ticket #373](https://www.assembla.com/spaces/tatoeba2/tickets/373)). NOTE: Be careful not to commit your config files. ## Getting to the real stuff ### Task assignments You don’t need to wait for Trang to assign you a task. You can - and are encouraged to - choose yourself what you’d want to work on. Whatever task you work on, make sure that there’s a ticket for it and that it’s assigned to you. If you want to work on a task that doesn’t have a ticket yet, you may create one and wait for confirmation from Trang that it’s a valid task, or you may talk about it with Trang and wait for her to create a ticket. Just make sure there’s a ticket before you work on anything. The point is that we shouldn’t find ourselves with two people working on the same thing at the same time. The tickets are here to let everyone know who’s working on what in order to avoid that. ### PHP CodeSniffer PHP CodeSniffer is a tool that helps maintain a coherent code by detecting violations of conventions and such. Such a violation might be a space or a missing newline, or it might be a method used in a class where it shouldn’t be used. Before you commit anything, you should run PHP CodeSniffer to detect such violations in your code and correct them. In order to run PHP CodeSniffer, you will need to have php-pear installed. Then, for those on Linux, there is a script on the root directory of the project. You will just need to run: ./phpcs [pathToDirectoryOrFile] For those on Windows, I don’t remember how I used to do it, but I will write it here when I find out again. NOTE: Tatoeba’s code still needs cleaning on that matter. When PHP CodeSniffer was set up, we spent a lot of time removing all the errors and warnings we could, but we didn’t go through everything. ### How and when to commit As was explained earlier, in the comment for the commit you should write a reference to the ticket your commit is related to (ex: re #373). Of course, always write a description of what you are committing. Don’t work on two different things at the same time. Or at least, don’t commit code that would refer to two different tickets. Split your commits so that each commit is only about one task. Of course you don’t have to wait until you’ve completely resolved a task before committing. You can commit your work in several steps. Again, make sure you don’t commit your config files. And again, make sure to run PHP CodeSniffer on whatever files you’re going to commit. ### Database updates In case a task requires a modification of the database, a script should be added in the folder docs/database/updates, named with the date of the day the modication was commited (in the format yyyy-mm-dd, for instance: 2013-06-28.sql). ### Testing We used to have a testing environment (dev.tatoeba.org) where not only devs but also regular users would do the testing before releasing the new code into Tatoeba. We don’t have this anymore since there wasn’t much change in the code in the past two years. Maybe we will set up again such an environment but in the meantime, the testing will only be done by developers on their own machines. Just to say that our testing phase sucks at the moment... ### Code review You should never be the only person who has seen the code that you commit. At least one other person needs to check it after you commit. For now, most likely it will be Trang. But there can be other people in the future. Also, if you are into these things, feel free to review any older parts of the code and suggest or make improvements. ### Everything else // TODO
version at: 29/06/2013, 17:51
# The ultimate guide for Tatoeba developers Somehow you've stumbled upon Tatoeba, somehow you've found the project really interesting, and somehow you decided to help us maintain and improve Tatoeba. But you're not sure exactly what you can do. This article is here to explain whatever you need to know to actually get things done. Note that this guide only applies to people who want to help with the current version of Tatoeba and for a substantial period of time. If you want to help for a shorter period of time, you can get the information you need here as well, but you don’t have to follow all the steps. ## Getting started ### Step 1 - Let us know Send us an email to team@tatoeba.org to inform us that you would like to help. Tell us when you discovered Tatoeba, your username on Tatoeba (if you have an account), how much experience you have in web development, how much time you think you can dedicate to Tatoeba, when you are usually available, and whether there is something specific you really want to work on. ### Step 2 - Take a look at the tickets We use a platform called Assembla to host the current source code. This platform has a [ticket system](https://www.assembla.com/spaces/tatoeba2/tickets), and this is where we will define all the tasks. This will give you a more precise idea of what needs to be done, and from there you can start deciding what you’d want to work on. You need to know that the code has not evolved much between July 2011 and April 2013 (so for pretty much two years), nor have the tickets. Some tickets may be outdated, some may be unclear, some may have been already solved but not closed. Trang is still in the process of cleaning, completing and reorganizing them. Look at the date when the ticket was created. If it was created after April 2013, it’s a valid one for sure. If the date is much older, then it may not be valid anymore. ### Step 3 - Install Tatoeba on your machine It’s all explained [here](http://en.wiki.tatoeba.org/articles/show/install-tatoeba-php). It can be practical for you to be on IRC while doing this (server: freenode, channel: #tatoeba). If you get stuck somewhere, other people in the channel can help you out. ### Step 4 - Your first commit In order to commit anything, you will need to be in the project team on Assembla. So you will need to [create an account](https://www.assembla.com/plans) there (just a free account), and tell Trang your username so I can invite you to the project team. You will then be given a very small task to do, so that you can make sure you are able to commit. Each commit should ideally refer to one ticket. This will be true of your first commit. Sometimes a commit may refer to no ticket, or to two tickets, but this should be exceptional. In order to refer to a ticket, you need to write in the comment for the commit “re #ticketNumber” (for instance: re #373). This way, the commit will appear in the ticket comments (cf. [comments for ticket #373](https://www.assembla.com/spaces/tatoeba2/tickets/373)). NOTE: Be careful not to commit your config files. ## Getting to the real stuff ### Task assignments You don’t need to wait for Trang to assign you a task. You can - and are encouraged to - choose yourself what you’d want to work on. Whatever task you work on, make sure that there’s a ticket for it and that it’s assigned to you. If you want to work on a task that doesn’t have a ticket yet, you may create one and set its status to "Pending", then wait for confirmation from Trang that it’s a valid task. Or you may talk about it with Trang and wait for her to create a ticket. A ticket is valid when it has the "Accepted" status. Just make sure there’s a ticket before you work on anything. The point is that we shouldn’t find ourselves with two people working on the same thing at the same time. The tickets are here to let everyone know who’s working on what in order to avoid that. Basically the process is: 1. **Pending**. Whenever a bug is reported or a feature is requested, a ticket is created with "Pending" status. 2. **Accepted** and **not assigned**. The ticket is reviewed. If it is validated, it will have the "Accepted" status. 3. **Accepted** and **assigned**. Whoever wants to work on the ticket can assign it to themselves. 4. **Test**. Once everything that needs to be done was done, it should be set to "Test" to indicate that it needs to be tested. 5. **Fixed**. The ticket will be set as "Fixed" after being rolled out and working fine on the prod version. ### PHP CodeSniffer PHP CodeSniffer is a tool that helps maintain a coherent code by detecting violations of conventions and such. Such a violation might be a space or a missing newline, or it might be a method used in a class where it shouldn’t be used. Before you commit anything, you should run PHP CodeSniffer to detect such violations in your code and correct them. In order to run PHP CodeSniffer, you will need to have php-pear installed. Then, for those on Linux, there is a script on the root directory of the project. You will just need to run: ./phpcs [pathToDirectoryOrFile] For those on Windows, I don’t remember how I used to do it, but I will write it here when I find out again. NOTE: Tatoeba’s code still needs cleaning on that matter. When PHP CodeSniffer was set up, we spent a lot of time removing all the errors and warnings we could, but we didn’t go through everything. ### How and when to commit As was explained earlier, in the comment for the commit you should write a reference to the ticket your commit is related to (ex: re #373). Of course, always write a description of what you are committing. Don’t work on two different things at the same time. Or at least, don’t commit code that would refer to two different tickets. Split your commits so that each commit is only about one task. Of course you don’t have to wait until you’ve completely resolved a task before committing. You can commit your work in several steps. Again, make sure you don’t commit your config files. And again, make sure to run PHP CodeSniffer on whatever files you’re going to commit. ### Database updates In case a task requires a modification of the database, a script should be added in the folder docs/database/updates, named with the date of the day the modication was commited (in the format yyyy-mm-dd, for instance: 2013-06-28.sql). ### Testing We used to have a testing environment (dev.tatoeba.org) where not only devs but also regular users would do the testing before releasing the new code into Tatoeba. We don’t have this anymore since there wasn’t much change in the code in the past two years. Maybe we will set up again such an environment but in the meantime, the testing will only be done by developers on their own machines. Just to say that our testing phase sucks at the moment... ### Code review You should never be the only person who has seen the code that you commit. At least one other person needs to check it after you commit. For now, most likely it will be Trang. But there can be other people in the future. Also, if you are into these things, feel free to review any older parts of the code and suggest or make improvements. ### Everything else // TODO