Development Guidelines for the openEHR Java Reference Implementation Project

Overview

The guidelines described below represent the quality assurance steps agreed by developers on this project, in ensuring the quality of the contents of the repository and its resulting software. The guidelines may be somewhat project-specific, and may be improved as time goes on. However, the statements below represent at any time the agreed approach of the team.

Builds

A build prior to commit should always be successful - the build process of the project should never break in any revision regardless if it's a public release or just internal development revision. For any java component project, it means run "maven clean test" should always ends with "BUILD SUCCESSFUL" - no compile error, no failed test. This requires the committers always run clean test locally before commit any changes.

The normal work flow together with subversion operation is as following:

start local copy - "svn co project_name"
OR
update local copy - "svn update" depends if there is a local copy or not
do changes locally, which is usually involves writing production code, writing test code, running test code to see if test pass or not
just before commit do last "svn update" and fix any conflicts
run "maven clean test" again if there is any new local changes
commit the changes using "svn commit"

Commits

Commit changes on a single component at a time (related to the 2nd point)
Provide a meaningful but short description of the changes made. It's used as the subject of email alerts sent to the project discussion list, so be concise!
Never commit anything that is broken (doesn't compile) or un-tested. The repository is not your backup drive.
It is OK that you current commit breaks the build of other dependent components, but it's your responsibility to fix the broken builds asap (preferably in the same working session). So it's good habit to check the status of our Continuous Integration Server after the commit. Later we should try to configure the CI server so that it will spam the developer who breaks the builds

Testing

The following guidelines apply to test cases and implemented features:

No test should be 'left behind' - when the production code gets updated and improved so does the unit test code. Broken test due to updates in the production code must be fixed so it can pass. Only when the feature in the production is deprecated, can the test be removed from the source.
No feature is considered implemented without according unit test runs successfully. One could even start with a broken test, and implement the feature in the production code and see the test passes, aka Test Driven Development. The point is that each feature in the production code should be accompanied by a unit test to provide minimal verification and serve as safety net when the production code evolves. Only when the production code is so simple that it can't possible break, then there is no need to test. Usually the unit test is organized in the same package as the production code but in different file directory.
Fixing a bug should always start with writing a unit test to demonstrate the bug with smallest amount of code possible, then proceed to production code to fix the bug and see the test passes. The initial test that exposes the bug should remain in the source tree.

Continuous Integration

When start to work with more than one components (kernel,parser) and worry about the dependencies between components, we need to have a build machine that can check out latest code from the subversion repository and run all the build script from individual projects (in the order of dependency) to see if any one fails, publish the result and notify the developer if anything goes wrong. This process should be triggered every time a change has been committed. Ideally, all developers should have the same environment as the build server and run integration test locally before commit any changes. But sometimes it could be too time consuming to do it locally (the build machine is usually a very fast one), so the developer could commit some changes and wait to see if the integration test passes on the build machine. If not, the developer is responsible to either correct (error in other project) or revert the change (most likely).

Browser not supported