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

Subversion can be thought of as a remote, versioning file system accessible via HTTP protocol, web browser and other tools. You can view the root of the filesystem with your web browser and drill into the files. All subversion operations are available through HTTP so this is a live view to the current state of the repository.

The top level directories and important subdirectories are explained below.

Release Tags

View /tags/project.

The project tags contain directories for stable releases for each project sub-component. You should never commit anything to tag directory but use it as a read-only space. For committing changes, use your personal workspace instead, as explained below.

Use tags for branching when you start new feature development:

 #
 # Start a branch from tag 2.0.2 to work on issue ORCJAVA-288...
 #

 # Checkout my workspace....
 > svn co https://svn.code.sf.net/p/openremote/code/workspace/myname               
 > cd myname

 # Copy from tag to start new development...
 > svn copy https://svn.code.sf.net/p/openremote/code/tags/project/\
   Controller/Controller_2_0_2 ./Controller_2_0_2_ORCJAVA-288

If for some reason your workspace has not been created yet, follow the instructions below. For valid tags, view /tags/project in our subversion repository.

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

Usually, your workspace has been already created for you, so check first by viewing the /workspace directory. If your workspace is not there, you can create it yourself:

 # 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://svn.code.sf.net/p/openremote/code/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 tags (these include alpha and beta tags and snapshots as well). Stable in the latter case means that they should at least compile. If you're unsure which tag to base your work on, ask one of the core developers.

Example 1

For example, to create a feature branch from tag 2.0.2 of Controller:

> cd workspace
> svn copy https://svn.code.sf.net/p/openremote/code/tags/project/Controller/Controller_2_0_2/\
   ./myusername/Controller_2_0_2_MYFEATURE
> svn commit -m "Created feature branch from /tags/project/Controller_2_0_2 tag" \
  myusername/Controller_2_0_2_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 and in your directory name which branch you've based your feature branch from.

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

Current source conventions are documented at Source Code Conventions. Do follow them for any new files you create. If you find older files that have not been formatted to follow these conventions, adhere to the least-number-of-changes principle described above, and follow existing conventions. Do not re-format any source files.