Coding Guidelines

From Buzztard

For editing source-code we use jEdit and Anjuta, but feel free to use any editor you are comfortable with.

[edit] Indentation

Eventually we will put an indent script into the cvs tool chain. For now, have a look at our code and try to write new stuff in the same way. It uses 2 spaces for indentation.

We got rid of all the tabs ;) with this shell one-liner:

find . -name "*.[ch]" -exec sed "s/\t/  /g" -i {} \;

We may rethink this decision based on this nice article.

[edit] Source documentation

We have decided to use gtk-doc for the documentation as it better fit with the gobject architecture. Read this how-to article for a introduction.

When documenting the API, add the comments to the *.c files and not to the *.h files.

1. Changing header files forces recompilation of the whole project.
2. We want to keep the headers small
3. Developers should use te API docs and not needing to look into the sources so much.

[edit] Naming conventions

Please try to follow the gnome coding style guides.

[edit] Commit message format

Like other GNOME project we use prepare-ChangeLog.pl to maintain ChangeLog entries. Additionally we use Tim Müllers version of David Schleefs cicl tool to commit changed files and diffcl to preview the changes.

[edit] prepare-ChangeLog.pl

This script generates a new ChangeLog entry for the developer. It needs the email address set in an environment variable. Add the following line to your $HOME/.bashrc or similar.

export REAL_NAME="Stefan Kost"
export EMAIL_ADDRESS=ensonic@users.sf.net

When a task is finished, just run

prepare-ChangeLog.pl
vi ChangeLog

You may use your preferred editor instead :). Add comments below the files to describe the changes. Do not just write "Fix a bug", try to be specific. You can include sf.net bugnumbers, by prefixing the number with a '#'. If the log entry lists files you don't want to commit, please remove them. For one example having different gettext versions among developers can cause po files to apprear in the log entry. If you have not change the po files yourself, remove the lines to avoid unnecessary commits.

To commit your changes use cicl.

[edit] cicl and diffcl

Cicl is commit-changelog. Instead of doing

svn ci .

now just run

cicl

This will simply commit all files listed in the top ChangeLog entry. The same way you can use diffcl to get a diff of the current changes (e.g. to sent them as a patch).

[edit] SVN tag/branch names

Developments always happens in HEAD. For some events we need to tag a snapshot. It would be good to agree on a scheme for tag names. We need tags to mark

• releases
  • RELEASE_0_1
• pre-releases
  • RELEASE_0_1_rc1
• points where we branch, when using a new (incompatible) backend API
  • SWITCH_GST_0_8__0_9
• points where we merge (do we merge?)
  • MERGE_SWITCH_GST_0_8__0_9__HEAD
• development branches
  • DEVELOP_xxx
  • REFACTOR_xxx

See the Release Guidelines page for commandlines for branching on releases. This is how you can do a development branch. Lets assume the current workdir has already related changes and you relaise its too much to finish it now, but still you want to commit it somewhere.

svn mkdir https://buzztard.svn.sourceforge.net/svnroot/buzztard/branches/REFACTOR_HIERARCHIC_PIPELINE
svn copy . https://buzztard.svn.sourceforge.net/svnroot/buzztard/branches/REFACTOR_HIERARCHIC_PIPELINE/buzztard/
svn switch https://buzztard.svn.sourceforge.net/svnroot/buzztard/branches/REFACTOR_HIERARCHIC_PIPELINE/buzztard/ .