Personal tools
You are here: Home → Community → Help Center → How-tos → Code Contribution Process

Code Contribution Process

This document describes the process that must be observed by PillarOne code contributors. Besides technical steps, it contains explanations and reasoning.

General Remarks and Motivation

Our paradigm: Many small iterations instead of a long specification phase followed by a longer implementation phase, in which it becomes clear that the specification won't work.

eXtreme Programming

There is always a danger in trying to achieve a perfect and complete first version. Normally an approach with several iterations is much more successful, as it is too hard to specify all things correctly from the beginning. Verifying ideas is essential.

Tests

In order to allow short and safe iterations, unit and functional tests are essential. Automated tests give developers a necessary safety net, alerting them if they break existing functionality.

Build Process

Whoever breaks something is responsible for fixing it. If he is not able to fix it due to lack of time or domain knowledge, he must contact the competent staff -- if possible in advance.

Pair Programming/Code Reviews

As we develop for a community, our code base has to be clean, well documented and understandable. Furthermore, knowledge should be shared among several persons. Therefore pair programming and code reviews are good measures to increase code quality.

Documentation

The first kind of documentation is test cases. A standard test should be called testUsage().

Usually, the first person to try to understand a code snippet is the one who originally developed it. Concise documentation is a real time-saver in a mid-term perspective. Documentation should be structured as follows:

Specification

Clear specification is the first documentation and should be in a form that another person is able to implement.

Specifications should concentrate on use cases. Implementation details should be left for the developer.

Before Coding

Mandatory steps: Update Issue Tracking, update your local copy of the repository.

It is essential that other collaborators know what you are working on. The last moment to enter an issue (Jira) is before you start coding. Ideally this is done long before and you only need to switch an issue to the state 'in progress'.

In order to avoid unnecessary and expensive merges, make sure to start on a current code base. However, before updating the current repository, its state (hudson) should be checked; updating is not recommended if the last build was broken!

Coding

Whenever possible, start with a test case and write the implementation afterwards.

Valuable code is tested and documented. Our goal is 100% test coverage. This is the basis for acceptance, fast development iterations and future refactoring.

After Coding

Contributed code changes must be committed to the code repository. Strictly following the steps below is essential.
  1. Successful tests: Before committing anything to the repository, all tests have to pass locally. The build process on the server can be simulated with the cc.build ant target. Verify that you have a reasonable first test coverage!
  2. Update before commit: Since your last update, another person may have committed changes. Not updating before committing can lead to the following results:
    • Commit itself fails if one of your modified files was modified in the repository by someone else since your last update. This will result in a conflict requiring a merge.
    • If the commit itself is successful, it may happen that your changes and the current repository version will break the build. Possible reasons may be: Constructors that are no longer available, refactorings such as moving or renaming, ...
  3. Run the cc.build ant target again. If the code base is under heavy development, the probability is quite high that tests will break even if they were successful in step 1. If things are broken and hudson tells you that the last build was successful, your changes must be the problem, even if you think it can't be the case.
  4. Fix what's broken. If this take long, return to step 2; if there was no other commit since your last update, you may finally commit.
  5. Wait for the 'build successful' mail. If you don't get one, your code changes were not careful enough and you are responsible to fix the build as fast as possible. If you are not able to resolve the problems on your own, look for help.
  6. Change the issue state in the tracking system.
Document Actions