This page prepares new developers to work on the R Synapse Client.

Retrieve the code base from Github

Create an account for yourself at https://github.com/.

Go to the central repository for the Synapse R Client: https://github.com/Sage-Bionetworks/rSynapseClient

"Fork" the repository, making a copy under your own Github account. (Look for the "Fork" button in the upper left corner.)

Now clone the repository to your local machine, creating two remotes, "upstream" is the central repo', while "origin" refers to your fork.  You will pull code from upstream  (the central repo) and push changes to origin.  Help on adding remotes: https://help.github.com/articles/adding-a-remote/ 

The development life cycle is diagrammed above:

1.  Pull the latest content from the 'development' branch of the central repository (normally referred to as the 'upstream' remote), with the command "git pull upstream develop".
2.  Create a feature branch off the main branch with the command "git branch -b <feature branch name>"
3. After completing work and testing locally, push to your fork (normally referred to as the "origin" remote) with the command "git push origin <feature branch name>"
4. In Github, create a pull request from the feature branch of your fork to the develop branch of the central repository.  Another engineer must review and accept your pull request.

Additional details are below.

Configure Eclipse (optional)

At Sage Bionetworks we use Eclipse as our IDE (http://www.eclipse.org/).  Use the StatET plug-in for R support. (http://www.walware.de/goto/statet)  Once you clone the Github project to your local machine, create project in Eclipse.

Get some work to do

The open work items (bugs and new features) are tracked in JIRA under the SYNR project.  Contact Sage Bionetworks for work assignment.  In JIRA assign the issue to yourself and change its state to "In Progress".

Create a feature branch

On your local machine make sure you have the latest version of the code base:

git checkout develop
git pull upstream develop

Now create a feature branch, named after the JIRA issue you're working on, e.g. for issue SYNR-1234:

git checkout -b SYNR-1234

Build the Client and run the test suite

Build the client

Once you've made changes it's time to build the client and run the test suite.  There are two ways to build.  Both paths download the Synapse object JSON schemas and auto-generate certain documentation files.  The first does a basic installation in just a few seconds:

1. tools/prebuild.sh
2. R CMD install .

The second option does a complete build, including 'vignettes'.  It requires LaTeX to be installed on your machine and takes a minute or more to run:

1. tools/build.sh

Run the test suite

Now start up R and run the test suite:

library(synapseClient)
synapseClient:::.test()

synapseLogin()
synapseClient:::.integrationTest()

".test()" runs unit tests, i.e. tests which do not contact the Synapse server.  ".integrationTest()" runs those tests that do contact the server, creating and deleting content as they go.

Push your code changes to Github

Commit your changes locally and push to your Github fork, e.g. using the following commands:

git commit -am "SYNR-1234"
git push origin SYNR-1234

In Github, create a pull request, from the feature branch in your fork to the develop branch in the central one.  (Look for the Pull Request button on the Github page for your fork.)  In Jira, change the state of the issue to "Waiting for Review."

Contact Sage Bionetworks to arrange a code review.  These are done live with the two engineers reviewing the code changes together.  This can be done via teleconference (e.g. Google Hangout.)  Often the meeting will identify changes that are needed before the pull request is accepted.  Make the changes locally and rerun the test suite.  When you push to your Github fork, the pull request will automatically be updated with your changes.  Notify the reviewer that the pull request is ready to be reviewed again and (hopefully!) merged.   Once the work is accepted, change the issues state in JIRA to "Resolved."

A continuous build system is triggered by the merge.  It checks out the head of the 'develop' branch and runs the sames test suite that you ran locally, ensuring your changes are compatible with other changes that have been merged in.  The Sage Bionetworks QA team will create a release candidate hosted on the "staging" partition of depot.sagebase.org for independent validation of correctness. Once the release candidate is validated it advances to the "prod" partition, available to all Synapse users.