Version at: 01/03/2014, 20:44 vs. version at: 02/03/2014, 22:53
11# Guide for potential Tatoeba developers
22
3NOTE: This page is out of date. It will be updated soon.
3**NOTE: This page is out of date.**
44
55Somehow 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.
66
77Start by **sending 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 programming/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. Note that there are effectively two development teams, one ("PHP Team") headed by Trang and another ("C++ Team") headed by sysko. Trang's team deals with software that is already online, while the functionality being developed by sysko is still mostly offline. If you already know which team you would like to join, please tell us in your e-mail.
88
99The remainder of the information on this page pertains to Trang's team. We will eventually add similar information for sysko's team.
1010
1111### Step 1 - Take a look at the tickets
1212
1313We 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. When you join Trang's team, she will add you to the list of people who can read and modify tickets.
1414
1515You 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.
1616
1717
1818### Step 2 - Install Tatoeba on your machine
1919
2020It’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.
2121
2222
2323### Step 3 - Your first commit
2424
2525In 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.
2626
2727Each 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)).
2828
2929NOTE: Be careful not to commit your config files.
3030
3131
3232
3333## Getting to the real stuff
3434
3535### Task assignments
3636
3737You 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.
3838
3939Whatever 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.
4040
4141Just 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.
4242
4343Basically the process is:
4444
45451. **Pending**. Whenever a bug is reported or a feature is requested, a ticket is created with "Pending" status.
46462. **Accepted** and **not assigned**. The ticket is reviewed. If it is validated, it will have the "Accepted" status.
47473. **Accepted** and **assigned**. Whoever wants to work on the ticket can assign it to themselves.
48484. **Test**. Once everything that needs to be done was done, it should be set to "Test" to indicate that it needs to be tested.
49495. **Fixed**. The ticket will be set as "Fixed" after being rolled out and working fine on the prod version.
5050
5151
5252### PHP CodeSniffer
5353
5454PHP 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.
5555
5656Before you commit anything, you should run PHP CodeSniffer to detect such violations in your code and correct them.
5757
5858In order to run PHP CodeSniffer, you will need to have php-pear installed.
5959
6060Then, for those on Linux, there is a script on the root directory of the project. You will just need to run:
6161> ./phpcs [pathToDirectoryOrFile]
6262
6363For those on Windows:
6464> chdir trunk
6565
6666> php PHP_CodeSniffer-1.2.1\scripts\phpcs app\path-to-file(s)
6767
6868NOTE: 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.
6969
7070
7171### How and when to commit
7272
7373As 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.
7474
7575Don’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.
7676
7777Of course you don’t have to wait until you’ve completely resolved a task before committing. You can commit your work in several steps.
7878
7979Again, 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.
8080
8181
8282### Database updates
8383
8484In 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 committed (in the format yyyy-mm-dd, for instance: 2013-06-28.sql).
8585
8686
8787### Testing
8888
8989We 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.
9090
9191Just to say that our testing phase sucks at the moment...
9292
9393
9494### Code review
9595
9696You 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.
9797
9898Also, if you are into these things, feel free to review any older parts of the code and suggest or make improvements.
9999
100100
101101### Everything else
102102
103103// TODO
diff view generated by jsdifflib

Version at: 01/03/2014, 20:44

# Guide for potential Tatoeba developers

NOTE: This page is out of date. It will be updated soon.

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. 

Start by **sending 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 programming/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. Note that there are effectively two development teams, one ("PHP Team") headed by Trang and another ("C++ Team") headed by sysko. Trang's team deals with software that is already online, while the functionality being developed by sysko is still mostly offline. If you already know which team you would like to join, please tell us in your e-mail.

The remainder of the information on this page pertains to Trang's team. We will eventually add similar information for sysko's team.

### Step 1 - 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. When you join Trang's team, she will add you to the list of people who can read and modify tickets.

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 2 - 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 3 - 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:
> chdir trunk

> php PHP_CodeSniffer-1.2.1\scripts\phpcs app\path-to-file(s)

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 committed (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: 02/03/2014, 22:53

# Guide for potential Tatoeba developers

**NOTE: This page is out of date.**

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. 

Start by **sending 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 programming/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. Note that there are effectively two development teams, one ("PHP Team") headed by Trang and another ("C++ Team") headed by sysko. Trang's team deals with software that is already online, while the functionality being developed by sysko is still mostly offline. If you already know which team you would like to join, please tell us in your e-mail.

The remainder of the information on this page pertains to Trang's team. We will eventually add similar information for sysko's team.

### Step 1 - 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. When you join Trang's team, she will add you to the list of people who can read and modify tickets.

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 2 - 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 3 - 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:
> chdir trunk

> php PHP_CodeSniffer-1.2.1\scripts\phpcs app\path-to-file(s)

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 committed (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

Note

The lines in green are the lines that have been added in the new version. The lines in red are those that have been removed.