HACKING

Contents:

• Version control
• Coding style...
  › ...for C++ code
  › ...for C and Python code
• Submitting patches


===============================================================================
Version control
===============================================================================

The current development version of telepathy-qt is available from the
'master' branch in the git repository:

  <git://anongit.freedesktop.org/telepathy/telepathy-qt>
  <ssh://git.freedesktop.org/git/telepathy/telepathy-qt> (for committers)
  <http://cgit.freedesktop.org/telepathy/telepathy-qt/> (cgit)

Stable branches are available from branches with names like
'telepathy-qt-0.2' in the same repository.


===============================================================================
Coding style
===============================================================================

For C++ code:
-------------

TelepathyQt uses the standard Qt coding style for the Qt/C++ code, as also
followed by eg. KDELibs.  The coding style is described in more detail in the
KDE TechBase at <http://techbase.kde.org/Policies/Kdelibs_Coding_Style>; in
short, it amounts to:

 * 4 spaces for indentation (no tabs, anywhere)
 * javaCase for variables and functions (incl. members), FullCamelCase for types
 * No abbreviations, except for 100% standard ones like regex, refcount, etc.
 * Type &var and Type *var, not Type& var and Type* var for pointers and refs
 * Use only one empty line to separate both groups of related statements AND
   function & class bodies
 * Use a space after each keyword but none after opening parens (if (true))
 * No spaces between the function name and the parens for the parameter list
 * Surround binary operators with spaces, but don't put spaces between a unary
   operator and their operand
 * For function bodies, put the opening curly brace on its own line. For
   everything else, put the opening curly brace in the same line as the
   statement (if, for, etc.) associated with it.
 * Use curly braces even for single-line bodies of conditional statements and
   loops
 * Prefer static_cast, const_cast etc over C-style casts
 * Wrap long lines to 100 characters at most
 * Use foreach, emit instead of Q_FOREACH/Q_EMIT
 * Don't write long (> ~5 lines) inline methods unless they are needed because of
   eg. template
 * Don't use references to QObjects
 * Destroy transient objects such as method call watchers as soon as possible
   rather than accumulating them to long-lived parent objects
 * Documentation should be in the source file instead of the header file
 * Public xxxInterface methods' definitions should be added to the end of the
   public methods declaration.
 * Always add friend struct Private declaration on classes that have Private
   structure.
 * Always add Q_DISABLE_COPY(xxx) to classes that cannot be copied.
 * Q_DISABLE_COPY(xxx) declaration must be placed on the top of the class
   definition, before the public keyword.
 * Methods should be ordered as follows:
    public
    public Q_SLOTS
    Q_SIGNALS
    protected
    protected Q_SLOTS
    private Q_SLOTS
    private
 * friend class xxx definitions must be placed right below the private keyword.
 * All exported classes should use TP_QT_EXPORT macro as following:
    class TP_QT_EXPORT xxx { ... };
 * Every issue in APIs which can (or will) only be fixed later should be marked
   with a doxygen \todo and have a corresponding fd.o bug filed and mentioned in
   the \todo annotation


For C and Python code:
----------------------

Parts of the regression tests — namely, those parts in tests/lib/glib/ — are
taken from telepathy-glib, and are written in C; the majority of the code
generation tools — in tools/ — are written in Python. Please follow
<http://telepathy.freedesktop.org/wiki/Style> for these.


===============================================================================
Submitting patches
===============================================================================

Patches should be made as (preferably) git branches or (last resort) -uNr diffs
against upstream git master, as found at:

  git://anongit.freedesktop.org/telepathy/telepathy-qt
  ssh://git.freedesktop.org/git/telepathy/telepathy-qt (for committers)
  http://cgit.freedesktop.org/telepathy/telepathy-qt/ (cgit)

Patches can be announced at the freedesktop.org bugzilla, using the product
"Telepathy" and component "tp-qt":

  https://bugs.freedesktop.org/enter_bug.cgi?product=Telepathy&component=tp-qt

If submitting a Git branch, please set the URL field of the bug to point to
your Git branch. Regardless of whether you are referring to a Git branch or
attaching patches, please specify the "patch" keyword on the bug.

For details on the code review procedure, see:

  http://telepathy.freedesktop.org/wiki/Review%20Procedure