Commits and coding style

Why this document

In order to have good quality in our software we must make it consistent, as easy as possible to read, make sure we can spot issues as quickly as possible and, eventually, make issues easy to fix (or avoid them at all). This document provides some guidelines about the minimal rules that apply both to external patches and to our members commits.

Coding Style

Writing code for some, maybe many, is considered a form of creative activity and as such it could be made into art as you can with painting, composing music or sculpture. We are humble enough to consider our code not that good and we'll strive to make it readable. The coding style reflects that:

Indentation rules:

• Use only spaces, tabs are forbidden. This way doesn't matter which editor you are using, the code will always look the same
• The lines should be 79 columns at most. There is still people using 80cols terminals around there, mostly because they use to have at least 2 or 3 source windows next to each other.
• Indentations must be 4chars.

Comment rules:

• Every new file should have a doxygen header explaining what the file is supposed to do
• You can be terse while commenting the code, but please give some hints about non self describing code (feng has plenty of it being either clarified or commented). That helps refactoring and debugging.
• Headers must have doxy comments and proper grouping
• Doxygen syntax must be the javadoc like one.

Syntax:

• If a function is used just internally make it static and avoid prototypes, just declare them in the right order. This makes the line count lower, helps debugging and let you avoid having to namespacify every function to avoid casual clashes.
• Try to avoid convoluted expression, e.g. use switches instead of if-chains
• Don't be afraid to use goto if you need to error out: just put your cleanup lines at the bottom of the functions with a label and goto it.

Commit/patch rules

Common rules:

• Commits (and patch) should be small, self contained don't break the compilation.
• Before committing or submitting a patch always make sure that the software builds and runs (some automated tests will be provided soon).
• Do not mix functional and cosmetic changes in the same submission.
• The comit message should be terse but should describe the purpose of the patch, don't be afraid to be less than serious, coding should be fun!

git commit -m "..." -a

git  commit -m "Cosmetics" files/that/I/just/reformatted
git-commit -m "Now with double coffee and theora bits" mediathread/*

Patch rules:

• patches should be in unified form (diff -u), you are advised to use git patch facilities since it makes sending and applying patches quite easier.
• Please give a verbose explanation of what it tries to do and why.
• Send them as plain text, compressed tarballs will be rejected.

Git Tutorial addendum

Here a list of useful snippets, some are taken from sourcemage wiki as integration to the git tutorial, another useful guide is in the wine wiki

Adding a remote branch

$ git clone git://live.polito.it/var/git/libnemesi
$ cd libnemesi
$ git branch sekrit
$ git checkout sekrit
#[hack... git commit hack ...]
#now publish it!
$ git push origin sekrit

Removing a remote branch

$ git push origin :sekrit

Tracking a remote branch

$ git checkout --track -b local_name origin/remote_name

Moving modules

Sometimes because we want to move some code from application to a common library (e.g. bufferpool used by feng and felix ) we need to update our application in a certain number of steps, this is a bare promemoria.

ALWAYS WORK IN SEPARATE BRANCHES

• If the code doesn't have an history to be preserved (e.g. few functional commits) just add it to the code in a single commit
• if you want to preserve the history
  • make a patch series with git-format-path with just the changes related to the files of interest
  • use git-apply to add the code.
• in a second commit update the build system and local code to work with the freshly imported one MAKE SURE YOU BUMP THE VERSION
  • check the Makefile.am
  • check the configure.ac
  • make sure all the headers are ok and the paths make sense
  • make sure everything builds
• merge the branch to the master.

Release steps

MUST DO

• make sure everything is in shape
  • try to build it in as many way as possible changing the configure flags
  • run each build against some testcases [maybe try to automate it if possible]
  • Double check documentation, manpages and doxy, grammar mistakes won't make the code fail but look bad.
• prepare the release documents
  • NEWS : should contain a synthetic summary of the changes, git-shortlog may help a lot
  • ChangeLog : should contain a relatively list of the changes, git log with the right format string can do that for us, if there is time delete the less meaningful commits
  • RELEASE : write a short essay on what we did and why people should use the new revision. Mention of known issue should be done there.
• tag the release
  • use git-tag -s -m “Release $version” v$version
• prepare the tarball

  $ git archive --format=tar --prefix=$app-$version/ v$version | (cd /var/tmp/ && tar xf -)
  $ cd /var/tmp/$app-$version
  $ ./autogen.sh
  $ doxygen
  $ cd ..
  $ tar -jcf $app-$version.tar.bz2 $app-$version

• put it on the website updating the pages and preparing a release newsitem.

OPTIONAL

• create packages for commonly used distributions.
• ping freshmeat.net
• have a party

Tools TODO

This is a pro-memoria about tools we should have ready and we ALWAYS forget about.

• A way to keep ffmpeg/vlc happy when we have to switch network (happens at ONU sometimes).
• A DUMB and SIMPLE tool to cut and paste raw streams (think about ds…)