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.