New Contributors Getting Started

You should be reading this document if you've completed the OpenRemote Contributor License Agreement. If you haven't yet but would like to contribute code back to the OpenRemote project, please let us know by email and we can help you complete this legal step and proceed with your Open Source contribution.

Once you have clicked through the ORCLA, you will need a write access to the Subversion repository. Our repository is currently hosted by Sourceforge and they do require you to register a user account with them in order for us to add you as a developer to the project (with read/write access to the source repository). Once you've registered your account with SourceForge, please notify us of the UNIX username you've chosen for yourself so we can add you as a developer to the repository.

We do use Subversion, and in particular we extensively use branching and merging capabilities of Subversion. Please make sure you are familiar with and comfortable with using Subversion for this. There's an excellent book resource available to get started with Subversion.

Subversion Directory Structure

Like all filesystems, the subversion repository has collected a lot of cruft. There are two main directories you need to care about:

Release Branches

• /openremote/branches/project

The project branch contains directories for stable release branches or development branches to become stable branches for each project sub-component. These are in general reviewed for features that are going to make it to the next release. Under normal circumstances you shouldn't commit anything to these (use your personal workspace instead, see below) but you can use them for reading or branching a new feature branch that you use in your personal workspace.

Developer Feature Branches

• /openremote/workspace

Here you'll find each developers personal feature branches. All development occurs here. The release branches are for merging code from these developer feature branches towards upcoming releases.

A feature branch can be anything from a new line of development, architectural refactoring, to a single feature development (with just a few commits) even down to a single bug fix (with a single commit). Creating branches are cheap so this is not an issue. Merging branches is hard, so try to follow instructions here and your changes will get merged back to release branches sooner.

Creating Your Workspace

First, create your workspace under /openremote/workspace:

 # Create your local work directory
 > mkdir mystuff               
 > cd mystuff

 # Checkout the workspace directory only, not including other developer branches
 # --depth=files saves you from a HUGE checkout that could take hours
 > svn co https://openremote.svn.sourceforge.net/svnroot/openremote/workspace --depth=files

 # Create and commit your directory, make sure you do it under workspace
 > cd workspace
 > svn mkdir myusername
 > svn commit -m "created my workspace" myusername

Creating a Feature Branch

Once you've got your workspace ready, you can create a feature branch under it (or bug fix branch or experimental branch, whatever you want to do).

You can branch from the stable release branches (these include alpha and beta branches as well). Stable in this case means that they should at least compile. Alternatively you can use any branch from under /tags directory in Subversion.

Example 1

For example, to create a feature branch from current alpha branch of Designer:

> cd mystuff
> svn co https://openremote.svn.sourceforge.net/svnroot/openremote/branches/\
  project/UIDesigner_2_0_0_Alphas 
> svn copy ./UIDesigner_2_0_0_Alphas ./workspace/myusername/Designer_2_0_0_Alphas-MYFEATURE
> svn commit -m "Created feature branch from /branches/project/\
  UIDesigner_2_0_0_Alphas" workspace/myusername/Designer_2_0_0_Alphas-MYFEATURE 

To keep things clean, it's a good idea to make a clean commit immediately after branching before making any of your changes. Also, it helps with later merging if you're clear in your commit message which branch you've based your feature branch from.

Example 2

You can also create your feature branch from another developer's work branch. Work branches may be unstable (no complete commits, do not compile) so you should communicate with the developer first to make sure the branch is usable. You can use the developer forums.

This example creates a work branch from a developer snapshot:

> cd mystuff
> svn co https://openremote.svn.sourceforge.net/svnroot/openremote/workspace/\
  juha/Controller_EP_SNAP_20111129 
> svn copy ./Controller_EP_SNAP_20111129 ./workspace/myusername/Controller_EP_SNAP_20111129-MYFEATURE
> svn commit -m "Created feature branch from /branches/workspace/\
  juha/Controller_EP_SNAP_20111129" workspace/myusername/Controller_EP_SNAP_20111129-MYFEATURE 

Synchronizing Your Branch

TODO

Commit Policies

When making commits, please follow the guidelines below. These are mainly to ensure the later merging of your changes to release branches is easier. Failing to follow these instructions means that reviewing and merging your changes will be delayed and in worst case rejected altogether!

Make Your Commits Small (Like, Tiny)

Make small commits. Really small. As small as possible. Even if you commit just one line at a time is fine. Really. Commits are cheap.

Small commits are easier to review and therefore easier to merge. Single line of code is quick to read and either accept or reject. Reading hundreds of lines of code is hard, consumes a lot of energy and may get pushed to another day.

Also, it is ok to commit one file at a time (even if they contain just one line change). Subversion is not the most friendly about breaking changesets down to smaller segments so keeping the commits small and committing one file at a time is fine. Even if the change in the file itself is not self-contained and requires later commits to compile. Don't worry about making atomic commits – we don't use trunk and release branches are only used as merge targets so making inconsistent commits in your own workspace is fine (no one else is using it yet except you). If you want to be nice, you can mention in your commit message that the particular revision you're committing won't compile by itself but will require additional revisions to be committed.

Do Not Commit Irrelevant Stuff

Get in the habit of checking what your commit is going to contain before actually hitting that 'svn commit' command. Really, do this. Commands 'svn stat' and 'svn diff' are your friends.

 # Tells us that two files are going to get added and one existing file is 
 # going to be modified if we commit from top level directory.
 #
 # Consider if committing files individually would be a better idea (see above!!)
 > svn stat 
   A       src/org/openremote/controller/deployer/DeviceProtocolBuilder.java
   M       src/org/openremote/controller/deployer/AbstractModelBuilder.java
   A       src/org/openremote/controller/deployer/Version20CommandBuilder.java

 # Shows us exactly what's going to be included in the commit.
 # Make sure these are relevant to your commit log. In particular,
 # make sure you're not committing formatting changes that might
 # have been automatically applied by your editor or IDE. This is
 # guaranteed to get a commit rejected!!
 > svn diff src/org/openremote/controller/deployer/AbstractModelBuilder.java 
Index: src/org/openremote/controller/deployer/AbstractModelBuilder.java
===================================================================
--- src/org/openremote/controller/deployer/AbstractModelBuilder.java	(revision 5261)
+++ src/org/openremote/controller/deployer/AbstractModelBuilder.java	(working copy)
@@ -44,7 +44,7 @@
  *
  * @author <a href="mailto:juha@openremote.org">Juha Lindfors</a>
  */
-abstract class AbstractModelBuilder implements ModelBuilder
+public abstract class AbstractModelBuilder implements ModelBuilder
 {
 
   /*
@@ -76,7 +76,7 @@
    * @return  the child elements of the root element
    */
   @SuppressWarnings("unchecked")
-  protected static List<Element> getChildElements(Element rootElement)
+  public static List<Element> getChildElements(Element rootElement)
   {
     return rootElement.getChildren();
   }

The point here is to make sure your commits are isolated to the relevant changes that you intend to commit and describe in your commit log. Avoid accidentally committing unrelated code changes (Subversion commands tend to be recursive so be careful about this).

The point here is again to make reviewing your changes easier when merging to release branches. Clearly commented commit that only contains the relevant files and lines to the actual change is quick and easy to do. Commit lots of irrelevant stuff with your actual change, and some people won't be particularly happy.

Avoid committing any formatting changes at all. This makes it very difficult to separate your formatting changes from your actual code changes. Reviewing your changes will be no fun at all, merging your changes with other people's changes in the same lines will be a pain in the behind, and you'll very likely see your commit rejected!

Communicate Your Intent

Communication is key. Describe what your commit intends to do in the commit log. Use either 'svn commit -m "message"' or 'svn commit -F file.txt' for longer multi-line comments.

Also, commenting your intent in the code helps. Again it makes review easier if we don't have to guess what you wanted to do or accomplish.

Finally, it is ok to leave notes in the source code comments. If you're unsure about if certain code behaves correctly, if there might be a corner case or exception case you didn't know how to deal with, or you just think further changes should be added later, just leave a note or a TODO in the source. That helps everyone.

Follow Source Code Conventions