Context Navigation

Versioning and Commit Conventions

Be aware of the conventions and respect them!

No files under version control in bin: Everything under bin is not under version control. If you want scripts put them inetc/scripts, they are all linked to bin on make automatically.

Avoid binary data: Binary data (blob) should be avoided whenever possible. Icons, pixmaps and other resources go to res. Camera images, map files etc. do NOT belong under version control.

Commit per feature - not per file

In the old days we often saw commits of pairs of matching .h and .c files. This was bad for two reasons:

The commit was not atomic and during committing there could be versions that did not compile.
This generated a lot of commit messages on the mailinglist that contained the very same content. Read on to the following note about atomic commits.

Commit atomic: Every single release of the software should be able to compile. We do not want broken builds. So if you made multiple changes which depend on each other commmit them in one go if at all possible! This also implicits to commit after each feature modification. Do not completely change a software component by adding or modifying several features but change one feature, test and commit this changeset. We have seen that this is not always possible (for example if comitting code to FireVision which is an external reference in RCSoftX). In that case make sure that you have all the code ready so that you can commit these changes in a short burst such that the possibly broken state is as short as possible.

Bundle dependent features: If you have added two features and they depend on each other commit both in one commit or if that makes the messages cleare bundle them in commits closely following each other.

Do _not_ commit minor changes: Think about your commit before to avoid having to make small changs afterwards. Code, Compile, Test - and check documentation using make quickdoc! Only if testing works (and you can "proof" with an QA application) commit the code to the repository. This is leveraged if you are on your private feature branch where you do not disturb others.

Version Control is not a copy tool: Do not use RCS just to copy config changes around. This was a nightmare for RCSoftX but this has been leveraged now by the Fawkes config subsystem. In general you should commit changes that you want to remain in the software, not an arbitrary file just to copy it around easier. You should also not commit just to get your code on the robot to test.

Commit message style: Your commit message should give a brief one-line description of the overall commit in the very first line of the message. This is helpful when browsing through the source for instance with the web interface to quickly see what was changed. Then have a list of changes and descriptions thereof after one blank line. If you are yet undecided about the bullet to use for your list use " * " which works fine with Trac (note the spaces). Close the messages with another blank line and your name on one line to claim credit.