FreeGuide Code Rules

The Benevolent Fascist Dictator Rule

Andy Balaam is the "benevolent" fascist dictator of FreeGuide. He runs the latest version of FreeGuide from git on his desktop. If you break FreeGuide so he can't use it for any reason, he will revert your changes until he can use it again.

It is crucial that developers be able to run the latest code. Otherwise new bugs simply don't get fixed, and the code base stagnates. If you are a developer, please use the git version as your normal desktop FreeGuide. If it breaks, let us know on the developers' mailing list, and Andy will revert the offending changes.

We apologise if this rules bites you - it's not supposed to be a punishment, it's supposed to guarantee that the developers are always running the latest code.

Send patches to the mailing list before committing

If you have developer access to the git repository, don't commit anything unless you have explicit permission from Andy Balaam. Instead, send a patch file to the developers' mailing list (see ContactUs) and wait for permission to apply it. The exception to this is when someone has been given control of a particular file or files, for example if you have made a translation or a plugin - in that case you may modify the files you control freely.

Follow the coding style

Please be very careful to follow the coding style we use within FreeGuide.

If someone can provide the Eclipse settings to enforce our style, please send them to the mailing list.

Unit test everything

We have a significant amount of legacy untested code, but new code and modifications to old code should be fully unit-tested, and larger-scale component tests should be written where needed.

Commits and commit messages

Each commit should be a logical set of changes, which you can summarise in a one sentence, e.g. "Added a check for a null reference when we save the IO controller configuration" or "Added a menu item that prints a whole week's personalised listings". After this summary, you should add as much useful detail as possible - try to think about what you would need to know if you wanted to merge this change into a different branch, or needed to revert it and wanted to know what the effect would be.

We prefer several small commits to one big one. If your code compiles and runs ok, it is worth thinking about whether you can commit it straight away before you continue. The more commits you split your work into, the easier it is to see which part caused a bug. If you can avoid it, don't save everything up into a single huge commit when it's "ready".

The exception to this is if the code you are committing doesn't get run. There's no point committing code that doesn't get run as it won't help us discover bugs in it until it actually runs. An example of this is if you're implementing a new menu action there is no point committing the code that does the action when you haven't added the menu item itself. On the other hand, if you can add the menu item but make it do nothing, that might be worth doing, since it could catch bugs like that item appearing in a different theme from the rest of the menu (yes, that is a real bug we had once...)

How do I get git access?

Under normal circumstances, you will be given git access when you have demonstrated an understanding of the code by submitting some good patches to the developers' mailing list.