= Getting Started with OpenSHA Development =
[[PageOutline]]

== Obtaining Source Code ==
Two options are available to obtain the OpenSHA source code:
 1. ''`Browse Source`'' on this website. Once in the ''`trunk`'' folder, the current release code may be downloaded as a zip file (the link is at the bottom of the page)

 2. Check the codebase out from our Subversion repository. Instructions on how to do this from within Eclipse are provided below.

=== 1) Download Eclipse ===

The latest version of Eclipse can be obtained from [http://www.eclipse.org/downloads/ The Eclipse Website]

The "Eclipse IDE for Java Developers" should be fine, however the Enterprise Edition (EE) will work as well.[[BR]][[BR]]

=== 2) Install the Subversion (SVN) Plug-in ===

The Eclipse SVN Plug in is called "Subclipse".

To install in Eclipse, follow the tutorial here: [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA Subclipse Installation]

(be sure to use `http://subclipse.tigris.org/update_1.6.x` as the update site when prompted)[[BR]][[BR]]

=== 3) Add the OpenSHA Source Repository ===

Once Subclipse is properly installed, from within eclipse:
 * Select ''`Window > Open Perspective > Other`''.
 * Select ''`SVN Repository Exploring`'' and hit ''`OK`''.

The ''`SVN Repository`'' tab should now be visible:
 * Click the ''`Add SVN Repository`'' button shown here...
[[Image(http://intensity.usc.edu/trac/opensha/attachment/wiki/SettingUpEclipse/svn_add_repo_button.png?format=raw)]]

 * Enter `http://intensity.usc.edu/svn/opensha` as the ''`URL`'' and hit ''`Finish`''.
 * Enter your ''`username`'' and ''`password`''.[[BR]][[BR]]

=== 4) Check out the OpenSHA Project ===

 * Click the arrow to expand the repository tree.
 * Right click on ''`trunk`'' and select ''`Checkout...`''
[[Image(http://intensity.usc.edu/trac/opensha/attachment/wiki/SettingUpEclipse/svn_checkout.png?format=raw)]]

 * If you are happy with the default options (they are fine for most people), just click ''`Finish`''.
     * To specify where to put your "Working Copy" of the project, click ''`Next`'' instead.
 * Be patient, it may take a little while to check out the entire project the first time.
 * Once it is checked out, switch to the Java perspective  ''`Window > Open Perspective > Java`'' (or ''`Other`'', then ''`Java`'').
 * More patience; it will probably take a little while to build the project as well (you should see ''`Building Workspace`'' in the lower right corner of the Eclipse window.[[BR]][[BR]]

----
== Working with OpenSHA ==

The instructions above will enable any registered user to get a copy of the ''`trunk`'' or current codebase. Any new code by authorized developers, however, must be committed to the repository on a ''`branch`''. The details of merging and branching are outlined in [http://svnbook.red-bean.com/ The SVN Book] and we encourage everyone involved to keep it handy. Some very basic instructions and guidelines are provided below.[[BR]][[BR]]

=== Branching ===
OpenSHA development occurs on branches. To create a branch:

 * Switch to the ''`SVN Repository Exploring`'' perspective (see Step 3 above).
 * Right click on ''`trunk`'' and select ''`Branch/Tag...`''
[[Image(http://intensity.usc.edu/trac/opensha/attachment/wiki/SettingUpEclipse/svn_branch.png?format=raw)]]

 * In the window that follows, enter in the ''`Copy to URL`'' field:

{{{
  http://intensity.usc.edu/svn/opensha/branches/username_branchname
  (replace ''`username`'' and ''`branchname`'' as appropriate)
}}}
 * Click ''`Finish`'' (or ''`Next`'' for more advanced options).
 * Once the branch is created, expand the ''`branches`'' folder and check out ''`username_branchname`'' as a "Working Copy" using ''`Checkout...`'' (see Step 4 above).[[BR]][[BR]]

=== Merging ===

When new code is ready for inclusion in a release, project admins will assist with any required updates to a developers branched code and with merging it into the main line of the project. 

[[BR]][[BR]][[BR]]