Version at: 23/02/2016, 15:22

# Guide for new Tatoeba developers

Somehow you've stumbled upon Tatoeba, somehow you've found the project interesting, and somehow you decided to help us maintain and improve Tatoeba... but you're not sure exactly how to get started. This page is here to guide you in your first steps.

## Get in touch with us

The first thing you need to do is to contact us and let us know about you. There are 2 main ways to get in touch with us:

- **Google group**: you should use in priority the [Google group](https://groups.google.com/forum/#!forum/tatoebaproject) to announce that you'd like to join the dev team. Note that the Google group is public and anyone on the Internet can see your post.
- **Email:** team@tatoeba.org (if you are too shy to post in the Google group).

Required:

- We will need to know your **Github username**.

(Optional) We would appreciate if you tell us a bit about yourself:

- Where are you from? Which languages do yo speak?
- How much experience you have in programming/web development? Don't worry, you don't need to be an expert or anything.
- How did you discover Tatoeba and what is your username on Tatoeba (if you have an account)?
- Is there something specific you'd like to work on?



## Github

Our source code is hosted on [Github](https://github.com/Tatoeba/tatoeba2) so you'll need to create an account there, if you don't already have one. 
If you are new to Git and/or Github, you'll have to spend a bit of time to learn about it. You'll especially need to understand how to open a [pull request](https://help.github.com/articles/using-pull-requests/).

On Github, take a look at our [issues](https://github.com/Tatoeba/tatoeba2/issues) and see if there's any problem listed in there that you'd like to try and solve.
Our issues are not perfectly categorized, but you can check the ones that are labeled [effort:low](https://github.com/Tatoeba/tatoeba2/labels/effort%3Alow) to get started.

## Install Tatoeba and explore the code

Before you start any task, you will need to install Tatoeba on your machine so that you can test your code before you send it to us.

The instructions to install Tatoeba can be found in the [README](https://github.com/Tatoeba/tatoeba2#tatoeba) of the Github repository.

If you have any trouble installing and running Tatoeba locally, do not hesitate to ask for help in the Google group.

You should then explore the code. In order to not get lost in the code, you will need to learn about [CakePHP](http://cakephp.org/). We currently use version **1.3**.
Note: Tatoeba's code is located in the `app` folder. You don't really need to look at the other folders.


## Your first tasks and pull requests

Somebody (most likely [Trang](https://github.com/trang)) will invite you to one of our teams on Github and will assign you an issue to work on. If you haven't done it yet, please tell us (or at least tell Trang) your username on Github.

At the beginning, you will only have **read access** to the repository. It means that you cannot push code directly to it, and must open a pull request in order to send a patch.
So again, if you are new to Github, please take the time to search and read about pull requests and about keeping your fork repository in sync with Tatoeba's repository. You will need to know about these things because you will be sending us code only via pull request for your first tasks.

Later on, if you are motivated to continue in the long term with us, we will move you into another team where you will have **write access** to the repo and won't necessarily have to open pull requests anymore (for small issues at least).


## Our workflow

### Website updates

We currently update Tatoeba more or less twice a month.

There is a [milestone](https://github.com/Tatoeba/tatoeba2/milestones) created for each update. If you've sent us a pull request and are wondering when your code will be integrated and deployed into production, you can simply check if your issue is added to one of the milestones.

You can check the [closed milestones](https://github.com/Tatoeba/tatoeba2/milestones?state=closed) to get an idea of what has been released in the past updates.

### Dev website

We have a [dev website](http://dev.tatoeba.org) where our users can test some of our code before we release the code on the real (production) website.

When we introduce changes, we will most of the time release it on the dev website first. We then ask our users to test and give feedback. We fix stuff or improve stuff based on the feedback. And then we release on the production website.

If you'd like to explore the features of Tatoeba without being afraid of polluting the database of the production website, feel free to use the dev website.

## Thanks for your interest and happy coding

That's pretty much all you need to know to get started. If there's anything that is not clear or if there's anything important to know for new developers that we didn't mention, don't hesitate to let us know.

version at: 27/02/2016, 20:55

# Guide for new Tatoeba developers

Somehow you've stumbled upon Tatoeba, somehow you've found the project interesting, and somehow you decided to help us maintain and improve Tatoeba... but you're not sure exactly how to get started. This page is here to guide you in your first steps.

## Get in touch with us

The first thing you need to do is to contact us and let us know about you. There are 2 main ways to get in touch with us:

- **Google group**: you should use in priority the [Google group](https://groups.google.com/forum/#!forum/tatoebaproject) to announce that you'd like to join the dev team. Note that the Google group is public and anyone on the Internet can see your post.
- **Email:** team@tatoeba.org (if you are too shy to post in the Google group).

Required:

- We will need to know your **Github username**.

(Optional) We would appreciate if you tell us a bit about yourself:

- Where are you from? Which languages do yo speak?
- How much experience you have in programming/web development? Don't worry, you don't need to be an expert or anything.
- How did you discover Tatoeba and what is your username on Tatoeba (if you have an account)?
- Is there something specific you'd like to work on?



## Github

Our source code is hosted on [Github](https://github.com/Tatoeba/tatoeba2) so you'll need to create an account there, if you don't already have one. 
If you are new to Git and/or Github, you'll have to spend a bit of time to learn about it. You'll especially need to understand how to open a [pull request](https://help.github.com/articles/using-pull-requests/).

On Github, take a look at our [issues](https://github.com/Tatoeba/tatoeba2/issues) and see if there's any problem listed in there that you'd like to try and solve.
Our issues are not perfectly categorized, but you can check the ones that are labeled [effort:low](https://github.com/Tatoeba/tatoeba2/labels/effort%3Alow) to get started.

## Install Tatoeba and explore the code

Before you start any task, you will need to install Tatoeba on your machine so that you can test your code before you send it to us.

The instructions to install Tatoeba can be found in the [README](https://github.com/Tatoeba/tatoeba2#tatoeba) of the Github repository.

If you have any trouble installing and running Tatoeba locally, do not hesitate to ask for help in the Google group or on IRC (server: freenode, channel: #tatoeba).

You should then explore the code. In order to not get lost in the code, you will need to learn about [CakePHP](http://cakephp.org/). We currently use version **1.3**.
Note: Tatoeba's code is located in the `app` folder. You don't really need to look at the other folders.


## Team invitation

You will receive an invitation to join one of our teams on GitHub. That's why we need your GitHub username.

At the beginning, you will only have **read access** to the repository. It means that you cannot push code directly to it, and must open a pull request in order to send a patch.
So again, if you are new to Github, please take the time to search and read about pull requests and about keeping your fork repository in sync with Tatoeba's repository. You will need to know about these things because you will be sending us code only via pull request for your first tasks.

Later on, if you are motivated to continue in the long term with us, we will move you into another team where you will have **write access** to the repo and won't necessarily have to open pull requests anymore (for small issues at least).


## Your first tasks and pull requests

If you managed to find an issue you want to work on, you can start right away. Just let us know that you want to work on that issue by posting a comment saying "I would like to work on this issue". Don't hesitate to ask questions if the issue does not have enough information.

You don't have to wait to be invited to our team and you don't have to wait for a confirmation from us before you start working on an issue. Just post your comment and start working in it.

If you haven't found any issue you could work on, somebody (most likely [Trang](https://github.com/trang)) will try to find for you an issue that should be easy enough to get started.




## Our workflow

### Website updates

We currently update Tatoeba more or less twice a month.

There is a [milestone](https://github.com/Tatoeba/tatoeba2/milestones) created for each update. If you've sent us a pull request and are wondering when your code will be integrated and deployed into production, you can simply check if your issue is added to one of the milestones.

You can check the [closed milestones](https://github.com/Tatoeba/tatoeba2/milestones?state=closed) to get an idea of what has been released in the past updates.

### Dev website

We have a [dev website](http://dev.tatoeba.org) where our users can test some of our code before we release the code on the real (production) website.

When we introduce changes, we will most of the time release it on the dev website first. We then ask our users to test and give feedback. We fix stuff or improve stuff based on the feedback. And then we release on the production website.

If you'd like to explore the features of Tatoeba without being afraid of polluting the database of the production website, feel free to use the dev website.

## Thanks for your interest and happy coding

That's pretty much all you need to know to get started. If there's anything that is not clear or if there's anything important to know for new developers that we didn't mention, don't hesitate to let us know.

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.