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!
Style and Documentation Guide Lines
We require everyone to ensure that the code follows our coding standard and is documented. You can check some rules by issuing:
make stylecheckmake doc
We also provide some editor configuration hints, which comply to our style. Have a look at EditorConfiguration.
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 Guide Lines
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:
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
Checkin Guide Lines
Useone 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 stylecheckmake docmake 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:
the commit fixed a bug
the commit added a feature
the commit removed a feature
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
refactor code, i.e. improve its quality without changing functionality
for transferring changes over branches via patches but without merging
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!
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
A description using it is needed here. The old description using mercurial has been removed.