+1 (669) 231-3838 or +1 (800) 930-5144

I recently started contributing upstream to the Open Daylight project (ODL) as a developer. I mostly followed the ODL developer documentation on how to get started and how to use the tools. Through ambiguous documentation or through hubris (every developer always thinks they know what they are doing), I made some mistakes and had to learn some things the hard way. This article is an enumeration of some of those hard knocks, just in case it can help the next person following this path.

First, this list is more than ten items. It is just that “top 10” has a catchy sound to it that just isn’t there for “top 17”.

Gerrit Workflow

Gerrit has a different workflow that you are likely using in downstream coding with other tools. There is a general tutorial and an ODL coding introduction to working with Gerrit that is very helpful.

Coding Conventions

We followed our own coding guidelines and those did not match to the Google coding conventions used upstream. Differences we ran into were:

  • Lower-case method names, even for JUnit test methods
  • Using the most restrictive visibility for access qualifiers (I won’t push back the philosophy of library design)
  • Use Java 8 lambdas everywhere possible

Gerrit Commands

Gerrit (plugin) has some non-obvious controls, namely that you can kick off another build by putting “recheck” as your comment. Others are “rerun”, “verify” as in here.

WIP

Upstream coders usually add the prefix “WIP: ” to their bug report to let other developers know things are not ready for prime time reviews yet. I have been putting the “WIP:” prefix as a new comment right after my new patch set.

Diffs

Mechanically you can review the issues by using “Diff against:” drop list to pick a revision to start at then go into the first file and then use the upper right arrows to move between files.

Broken Master

The master branch on ODL can and does break, causing lots of down time with broken builds (days even). Full builds take 10 hours and verifying-before-pushing is an evolving process. Have patience.

Git Review

If you are using “git review” and you forgot the “- – amend” option on your commit, you will be prompted to squash and will end up with a new branch. You can recover using “git rebase -i HEAD~2” then using the force option and then abandoning the new branch.

Staleness

Along with master breaking, master can also produce stale artifacts, so don’t assume that clearing your m2 cache, creating a subproject repo and building will give you up-to-date code.

Searching Jars

You can search jar files using find . -type f -name ‘*.jar’ -print0 |  xargs -0 -I ‘{}’ sh -c ‘jar tf {} | grep “YourClassHere” &&  echo {}’ for helping verify your m2 has the latest.

Patch Workflow

The patch workflow is not very good at all for having multiple people working on an item; traditional git branches and management are superior in this respect so expect some pain.

Broken Master Again

If your patch won’t build because master is broken, you can rebase it to pick up a fix temporarily. When you do a “git review” to push it, you will be prompted because there are two commits (your new patch revision and the fix). You do not want to merge that fix into your patch.

Skip Tests

There may be a bug here or there in dependencies, so you should always to a full build within a subproject the first time after you create the repo. In my case, I was in netconf and saw a difference between starting off with a “-DskipTests” or not. The former lead to a failed build, while starting with a full build (and then doing any number of skip tests), seemed to work.

Checkstyle

If you are a developer who works with meaningful coding standards, you will find yourself clashing with the pedantic nature of ODL’s use of check style. Although it probably varies from project to project, your code reviewer might decide that your code is the perfect opportunity to enforce check style.

Bug Report

Put the URL to the gerrit issue in “external references” on the bug report and put the bug as the first part of the commit message like “BUG-8118: ….”

Gerrit Patch Set

Any replies that you make to the patch set discussion use the current patch set as an annotation. Be sure to move your “current patch set” by using the upper right drop list “Patch sets 8/8” (for example).

Easy Debug

You can do development on a project like netconf and start a controller with your code: git clone, mvn clean install, go to netconf/karaf/target/assembly/bin, do ./karaf, at console install your feature, like feature:install odl-netconf-callhome-ssh (and maybe odl-mdsal-apidocs). Viola!

Docs

If you work on the docs, then you need to know there are three kinds: contributor (on wiki), developer, and user (both on docs.opendaylight.org).

Pin It on Pinterest

Share This