[[PageOutline(0-7, Table of Contents, floated)]]

So, you want to do some contribution for iPeer project. Just follow the following steps to make your own local development environment.

== Setup ==

=== For External Developers and Contributers ===
1. Get a !GitHub Account from https://github.com. 
2. Install Git on your local computer.
 * Mac: http://help.github.com/mac-set-up-git/
 * Linux: http://help.github.com/linux-set-up-git/
 * Windows: http://help.github.com/win-set-up-git/
3. Fork the iPeer project (https://github.com/ubc/iPeer) into your account and  clone the code from your forked repo: http://help.github.com/fork-a-repo/ 
4. Additional steps to set up
 * Pull the Guard plugin.
{{{
cd ipeer
git submodule init
git submodule update
}}}
5. Setup [wiki:CodingStandard coding standard]
6. Starting developing~
7. Once you finished, you can issue a pull request so that we can merge your changes to the iPeer repo. http://help.github.com/send-pull-requests/

=== For Internal Developers and Contributers ===
1. Follow steps 1 and 2 for External Developers and Contribuers above
2. Follow the steps in https://help.github.com/articles/generating-ssh-keys to generate a ssh key for your github account
3. Clone the code
{{{
git clone git@github.com:ubc/iPeer.git
}}}
4. Additional steps to set up. Pull the Guard plugin.
{{{
cd iPeer
git checkout dev
git submodule init
git submodule update
}}}
5. (XAMPP) go to xampp/htdocs/app/plugins/guard/config, open guard.php. You will have to do something similar if you are using any other web server.
* Make the following changes
{{{
//$config['Guard.AuthModule.Name'] = 'Shibboleth';    // Using Shibboleth module
$config['Guard.AuthModule.Name'] = 'Default';     // Using default (build-in) module
}}}
* Copy guard.php to xampp/htdocs/app/config

See, that's not very hard.


== Debugging ==
=== For version 2.x ===
To turn on debug mode, change the line in file app/config/core.php from:
{{{
define('DEBUG', 0);
}}}
to
{{{
define('DEBUG', 2);
}}}

=== For version 3.x ===
To turn on debug mode, create a local configuration file under app/config/config.local.php with the following content:
{{{
Configure::write('debug', 2);
}}}

== Running Vagrant (Virtual Environment) ==
Follow the instructions in https://github.com/ubc/iPeer/blob/dev/readme.md#running-virtual-development-server.

== Running Tests ==
In order to run tests, you will need [http://www.phing.info/ Phing] and [http://pecl.php.net/package/oauth OAuth] (required to run controller tests). You also need to set up a test database, named the same as your database in app/config/database.php with suffix "_test", e.g. ipeer_test.

To run the tests, simply call the following commands at the root of the directory:
{{{
phing test
}}} 

== Branching Strategy ==
Branches in public repo and the purpose of each branch:
 * 2.x: iPeer 2.x code base. Each commit on this branch will be a new version to release.
 * dev: The branch we are working on day to day
 * master: iPeer 3.x code base. Each commit on this branch will be a new version to release.
You can/should  create local branch if you are working on a new feature or non-trivia bug fix. Then merge back to dev. You may use rebase or not depending on the complexity of the work.

There are also some changes on Jenkins setup.  There are 5 jobs: [http://ci.ctlt.ubc.ca/job/iPeer2/ iPeer2], [http://ci.ctlt.ubc.ca/job/iPeer3/ iPeer3], [http://ci.ctlt.ubc.ca/job/iPeer_dev/ iPeer_dev], [http://ci.ctlt.ubc.ca/job/iPeer_Release_2.x/ iPeer_Release_2.x] and [http://ci.ctlt.ubc.ca/job/iPeer_Release_3.x/ iPeer_Release_3.x].
 * Any push to 2.x branch will trigger iPeer2 job. If the job success, iPeer_Release_2.x will be triggered and will publish a new version for 2.x.
 * Any push to master branch will trigger iPeer3 job. If the job success, iPeer_Release_3.x will be triggered and will publish a new version for 3.x
 * Any push to dev branch will trigger dev job. No release will be published.

Old and new branches mapping (branches renamed as of Nov 18th, 2012)
 * master -> 2.x
 * cakephp1.3 -> dev
 * cakephp1.3 -> master
 * removed compatibility branch

NOTE: The branching strategy we are using is based on the page: http://nvie.com/posts/a-successful-git-branching-model/.

== Workflow ==
The standard workflow is as the following:
* Pull the latest code
{{{
git pull
}}}
* Depending on the task, work on ''dev'' branch or create a local branch. Use frequent branching and small commit. Do not combine several tasks into one commit.
* Write some code
* Rung unit tests and integration tests
{{{
phing test
}}}
* Run your own manual tests
{{{#!div style="background: #dfd; border: solid 1px #8f8; float: right; padding: 0; margin: 0; width: 15em;"
 '''Tip''': The ticket can be closed with a command in the [http://trac.edgewall.org/wiki/CommitTicketUpdater commit message].
}}}
* Merge back to dev branch (not necessary if working on ''dev'' branch)
* Push the changes to github
{{{
git push
}}}
* Close any related [/report/1 tickets] if there is any


==  Auto Deployment ==
When a push is send to Github, it will trigger a build command on the [http://ci.ctlt.ubc.ca continuous integration server]. It will run the tests and checking, e.g. styles, code duplication, etc, to make sure everything works fine. If the build is failed, you should exam the code and fix it.

If the build is successful, the CI server will deploy the code to our test server for further testing. Different branch will be deployed to different domain.
* dev branch -> http://ipeerdev.ctlt.ubc.ca
* master branch -> http://ipeerverf.elearning.ubc.ca
* 2.x branch -> http://ipeerverfv2.elearning.ubc.ca