Developer Guidelines

We strongly encourage every developer or contributor to follow these rules (not only for passing code reviews). They should help you in building great software. Of course our tools are not perfect, but if you have ideas on how to improve, do not hesitate! Contact us!

Install Prerequisites

Linux:
Mac:
Windows:

Style and Documentation Guidelines

We require everyone to ensure that the code follows our coding standard and is documented. You can check some rules by issuing:

make stylecheck
make doc

We also provide some editor configuration hints, which comply to our style. Have a look at EditorConfiguration.

Checklist:

follow the CodingStandard
follow the TextCapitalizationRules
document all code
if you find code un- or improper documented, fix it immediately or contact us if you can't.

Unit test framework (optional, if you want to contribute)

At the moment we use CxxTest, but this might change to either gTest or Boost Test in near future.

Linux and Mac OSX: For installing CxxTest on a Linux host which uses RPMs you may try the noarch-RPM. For all others get source and install it like this:

tar xzf cxxtest-3.10.1.tar.gz mv cxxtest /usr/local cd /usr/local/bin && ln -s ../cxxtest/cxxtestgen.py cd /usr/local/include && ln -s ../cxxtest/cxxtest

Then you may use it like this:

#include 

class MyTestSuite : public CxxTest::TestSuite
{
public:
    void testAddition( void )
    {
        TS_ASSERT( 1 + 1 > 1 );
        TS_ASSERT_EQUALS( 1 + 1, 2 );
    }
};

be sure to place your test always in a test directory and if you need fixtures, make them as small and minimalistic as possible and place them in test/fixtures. Also document your tests as well!

Testing Guidelines

Unit-testing is a very important part of OpenWalnut. At least the core functionality is tested. You should add tests for your code too. To ensure that all the tests work issue:

make test

Checklist:

each test, tests just one thing
When adding new features, write (failing) test first. This gives you the idea how you want to use your new feature. See test driven development for further details.
add tests for your classes where possible
try to cover as much of your work as you could
don't test things that cannot break (this is not always easy to see, but a simple getter just returning unmodified data, will not fail) or that are very trivial, e.g. when printing each step in a for loop from 0..99 just the loop step, we don't have to write 100 tests! Tests are not meant for proofing the program.
extend existing tests of you extend existing classes
issue the test- target make test to ensure all tests work
for polymorphic classes, test each class in the inheritance tree separately
- especially test only the functionality the class implements itself

Commit Guidelines

Use one fixed identity in your ~/.gitconfig with a valid email address!

If you want to commit changes, you also have to follow some rules. At first, make sure the style, doc and test guide lines where followed. You can check it like this:

make stylecheck
make doc
make test

on the command line. This also ensures that non-compiling and test-breaking code does not get committed. This is important when using git bisect for debugging.

Commit- messages also need to follow a certain scheme. Although not everyone is allowed to commit and push into our repository, it is surely useful for others to understand our commit messages. A typical commit message looks like this:

[XXX #1234] Short summary ...
 * description details...
 * ...

where #1234 is a (optional) corresponding ticket number and XXX is one of:

Tag	Description
`FIX`	the commit fixed a bug
`ADD`	the commit added a feature
`REMOVE`	the commit removed a feature
`STYLE`	code change to follow coding style rules, of course code that doesn't follow the coding style shouldn't be in the repository in the first place
`CHANGE`	code change (use carefully, because it is quite general, try to be more precise)
`REFAC`	refactor code, i.e. improve its quality without changing functionality
`CLEAN`	code clean up
`DOC`	added and/or improved documentation and/or comments
`MERGE`	merged different heads or branches
`DUMMY`	for other purposes
`REVERT`	undo a changeset
`PATCH`	for transferring changes over branches via patches but without merging
`CLOSE`	for closing a branch

Those tags are meant to give a quick overview over a list of commit messages. They don't replace the commit message itself. The tag must be upper case. So please always add the tag and a telling description in English language. If you have a commit where you add a feature and also fixing a bug, make two commits if possible!

Checklist:

ensure the style, doc and test guide lines (see above)
- do not commit if it fails
do not commit non-compiling code
add one of the above tags and a ticket number if it exists
provide a short description of your change

Closing Branches

A description using it is needed here. The old description using mercurial has been removed.

GitLab