Code Management

As a software development collaboration, the management of the common code base is of primary concern. This chapter describes the best practices for the collaboration.

Licenses

Apache 2 is the primary code license of the collaboration. Although, exceptions can be made for specific cases (e.g. plugins to libraries under a different license), all core software must be under the Apache 2 license to ensure that it can be legally integrated into a common distribution and to ensure the widest possible reuse of the software.

High-level documentation (e.g. User’s Guide) is released under the Creative Commons Attribution license to ensure its widest possible distribution. Documentation integrated with the code (e.g. README) are released under the same license as the code itself.

All non-trivial source code files, must have a comment block at the beginning of the file declaring the license for the code. This block must also contain the copyright statement for the file. The copyright is held by the original author (or author’s institute) and must also appear in this initial comment block.

Preferred Languages

To maximize the number of people who can contribute to the maintenance and development of the StratusLab software, the collaboration attempts to minimize the number of development languages used within the project.

On the server side, the collaboration prefers the use of Clojure (on the JVM) and Java. Historically, all of the services developed by the project have been written in Java; more recently this has been shifting towards Clojure.

On the client side, Python is the preferred language. The StratusLab client is nearly entirely written in Python and many of the utility scripts (e.g. binding to Libvirt) are migrating from shell to Python.

Exceptions are made for specific cases. For example, server startup scripts are written in bourne shell. If in doubt, ask for feedback via the developers’ mailing list.

Repositories

All of the code for the collaboration resides in GitHub under the “StratusLab” organization. Generally, each major service resides in its own repository.

All developers have write access to all repositories. This allows everyone to contribute to any of the services and to correct bugs as they are found. Nonetheless, major changes in a repository should be discussed on the developers’ mailing list and with the primary developer of the service.

Build System

The collaboration has chosen to use Maven as its build system. Consequently, all of the code is built using the standard Maven workflows. The collaboration maintains a common top-level pom.xml file to manage plug-ins and dependencies. New dependencies should be discussed on the developers’ mailing list and then added to the top-level pom.

Code Quality

Issues

Significant changes to the code and specific bug fixes should be tracked via GitHub issues. These issues should also be tied to milestones so that release announcements can be prepared. Reference the Issue ID number in the commit message, so that GitHub will automatically cross-reference the commit to the issue.

Code Formatting

Developers should generally follow the well-known style guides for their code. Specifically,

Spaces are preferred over tabs with indentation depending on the language (2 for Clojure; 4 for others).

IDEs such as Eclipse, IntelliJ, and PyCharm make formatting the code to these specifications easier. Their use is recommended.

Static Analysis

Where possible, static analysis of the code should be integrated with the build process.

For Java, FindBugs is an excellent tool for finding common errors through the static analysis of the generated bytecode. All Java-based project, must run FindBugs as part of the build process. Any “critical” problems identified by FindBugs must be corrected before committing the code.

For other languages, you may wish to integrate similar tools in the build process. For these other languages, we do not have specific recommendations.

Unit Testing

All of the StratusLab code should use unit testing to ensure that the code behaves as expected. These unit tests are especially critical when refactoring code (something that happens fairly frequently!).

The code should use the appropriate xUnit framework for the programming language being used. Ideally, the unit test reports should be formatted in the JUnit XML format to allow better reporting from the continuous integration tools.