CoffeeAndPower/seabiscuit

= Overview = This page is intended to serve as a quick primer for anyone interested in contributing to the Coffee &amp; Power Android Application, codenamed 'Seabiscuit'. As a starting point, you should have an account setup on http://worklist.net.

= Software Requirements = The following are the suggested requirements for the development environment of anyone working on the Seabiscuit project.

Eclipse
The standard development environment for Seabiscuit includes Eclipse. Note that you can develop Android applications (Seabiscuit included) without Eclipse, but we're not documenting that here.

The main page to download Eclipse is here: http://www.eclipse.org/downloads/

Minimum Required Version: Eclipse 3.6 (Helios) Recommended Version: Eclipse 4.2 (Juno)

For convenience sake, you can obtain the Juno release for Java EE developers here: http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/junor

Eclipse Best Practices (Recommended)
The following preferences should be set in Eclipse:
 * General > Editors > Text Editors
 * Displayed tab width: 4
 * Insert spaces for tabs: checked
 * Show print margin: checked (recommended)
 * Show line numbers: checked (recommended)
 * Show whitespace characters: checked
 * XML > XML Files > Editor
 * Indent using spaces: selected
 * Java > Code Style > Formatter
 * Goto: https://github.com/android/platform_development/tree/master/ide/eclipse
 * Download and Save 'android-formatting.xml'
 * Select 'Import'
 * Browse to above file and open
 * Java > Code Style > Organize Imports
 * Goto: https://github.com/android/platform_development/tree/master/ide/eclipse
 * Download & Save 'android.importorder'
 * Select 'Import'
 * Browse to above file and open
 * Java > Compiler
 * Compiler compliance level: 1.6

Android SDK
You can skip this step because normally after the installation of the ADT in the next step, the Eclipse tooling allows to download the Android SDK automatically.

For manual installation of the Android SDK, following the directions provided by the Android developer site as noted below:
 * http://developer.android.com/sdk/installing/index.html
 * http://developer.android.com/sdk/installing/adding-packages.html

Note: The minimum API version required (Android SDK) as declared in the manifest is API level 8 (Froyo/2.2) so this should be considered the minimum tool level required (with corresponding ADT plugin). There is no  targetSdkVersion declared, but given our use of the v13 compatability library, this should probably be set to 13 explicitly.

Android Developer Tools (ADT) Plugin for Eclipse
To install the ADT Plugin, follow the procedure available here: http://developer.android.com/sdk/installing/installing-adt.html

The wizard will ask you to install the SDK if it is not already installed.

Subversion (SVN) Client
The Seabiscuit project uses Subversion for it's source control repository. There are a number of options that you can use to access the repository. We recommend using an integrated solution, via an Eclipse plugin but at the end of the day, feel free to choose the one that works best for you:


 * Subversive SVN Team Provider (Plugin for Eclipse)
 * In the Help menu, select "Install New Software"
 * In the dialog, first select: "Juno - http:// ....."
 * Then in the list opens "Collaboration"
 * At the end of Collaboration list you should find "Subversive SVN Team Provider"


 * Subclipse SVN Client (Plugin for Eclipse)
 * In the Help menu, select "Install New Software"
 * Add update site for http://subclipse.tigris.org/update_1.6.x/
 * Select all available software (recommended - note best results appear to be using JavaHL)


 * Standalone client like TortoiseSVN
 * Git bridge git-svn

= Getting the Code =

When you want to get a fresh copy of the Seabiscuit project, do the following:
 * Right click on the project view
 * Select "New" > "Project ...", then in the list open "SVN" > "Project from SVN"
 * Use the following url for the SVN repo:
 * http://svn.worklist.net/svn/repos/seabiscuit

Note: the correct project is 'CPAndroid' - the 'CoffeAndPowerAndroid' project is not current, it will be removed/archived as it is likely to just confuse new developers.

Important: don't go through the new project wizard. Otherwise, it is likely that that project.properties file (which is included under source control) will be overwritten, resulting in compilation errors.
 * When checking out the source, it should be checked out as an Eclipse project

= Set-Up and Testing on a Virtual Device = To set up a virtual device, just follow the instructions provided by the Android developer site: http://developer.android.com/tools/devices/index.html

= Providing APK for Functional Review =

When you're ready to show what you've done:

Follow this procedure to sign your application: http://developer.android.com/tools/publishing/app-signing.html It is recommended that you sign in release mode for release to other users.
 * Right click on your project, select "Android Tools" > "Export Signed Application Package" in the menu.

= Providing Diff for Code Review =

Make sure that you update your repository (svn update) before providing your diff to ensure that your changes reflect the latest code base.


 * In Eclipse, create a patch file as follows:
 * Right click on your project, select "Team" > "create patch"
 * Paste the patch file content here: http://paste.worklist.net/
 * Select 'Diff' syntax highlighting for easier readability
 * Copy the paste bin url into the comment of your job, it will be used by another developer to make the code review.

= Committing Code to the Project =

Once your change has been reviewed and everything looks good, you will be given the go ahead to make your commit. You can commit your changes directly from your local svn client (i.e. eclipse workbench with svn plugin).

Note that you will receive svn commit credentials only after your first job has passed the functional/review stage. Until then, you will only be able to checkout/update from the repository.

= Frequently Asked Questions (FAQs) =

The following is a list of questions that have been asked at one time or another. If you would like to see something added, see "Where can I ask questions/talk to other people working on Seabiscuit?" below.

Q: What is the SVN Repository for the Coffee and Power Android APP?
A: http://svn.worklist.net/svn/repos/seabiscuit

Q: What is the current project for the Coffee and Power Android application?
A: CPAndroid

Q: I just checked out the code and I'm getting a compilation error on the project, what gives?
A: Make sure that you have checked out the source as an existing eclipse project and confirm that the project.properties file contains the following target definition: target=Google Inc.:Google APIs:8

Q: Where can I ask questions/talk to other people working on Seabiscuit?
A: https://www.worklist.net/worklist/journal.php come on over and introduce yourself.

Q: Just who/what is this 'Seabiscuit'?
A: Token wikipedia link: http://en.wikipedia.org/wiki/Seabiscuit

= TODO =
 * links/documentation on Worklist states/flows/roles