Contributing Patches
From PsiWiki
We welcome any contribution to the codebase. This page will give more information on how to get your patches accepted in the Psi main codebase.
Contents |
Before you start coding
If you haven't started coding yet, here are a few words of advice. If you have a specific feature you want to implement, you may want to check with the developers if no one is implementing it yet. They might also give you extra tips on how to implement it, which will help in getting your patches coded and accepted faster.
If you don't know what to implement, but want to help out, you can go through Flyspray and make your choice. If you made your choice, double check with a developer to see if it is a feasible choice. By the way, we welcome bugfixes more than anything else !
One change per submission
If you want to implement several features and submit them, please do! The relevant rule here however is that there should only one purpose for each patch. A major refactoring of code, together with a new feature, and some other tweaks is very unlikely to be committed; it's too difficult to check submissions this way. Darcs makes it very easy to do sequential work, so please only perform one task per submission.
Code documenting
In order to ease up understanding of the Psi Code, it has been decided to accept only documented patches. The Psi sources right now are not very documented, but this will change in the future - the Qt4 rewrite might bring better documentation already.
The documenting should be done in Doxygen syntax.
Code style/convention
Fitting in
As a general rule - try and fit in with the existing code styles used - the easiest way to do this is to find a modern class, and see what style that is written in. Psi devs are very fussy about styles and patches which don't fit into the coding styles simply don't make it to mainline.
Basics
Basic Psi style: Linux, with 1 tab indentation.
Class, structure and namespace names should start from UpperCaseLetter. Variables and function names should start from lowerCaseLetter. And you shall forget about hungarian notation existance.
All classes and functions should be documented using Doxygen.
Globals / Singletons
If you think you want a global variable, or some member of PsiCon which is accessed throughout Psi, you almost certainly don't, and almost certainly want to use something like a singleton instead.
Singletons themselves aren't ideal because they make unit testing almost impossible, so steer clear of those too.
Spaghetti Code
If you're adding new code to an existing method, please consider the impact it has upon readability - it's easy for a 10 line method to grow by 5 lines a time in patches to something unmanageable. Additionally, we're making an effort to ensure all the code in Psi is beautiful - as such, we're no longer likely to accept patches which don't fit our idea of code beauty
Classes
Please put just one class in one file, so for example there should be just the MyClass class in myclass.h and myclass.cpp files. Class names are CamelCased, and filenames are all lowercase.
Traditionally, it has been advised to use PIMPL to conceal complex inner data structures away from the header files. An example can help you understand the C++ PIMPL idiom. These days, however, it's going somewhat out of fashion with the Psi devs, and patchers should consider whether it's necessary or not, if in doubt, have a chat on the development mailing list.
Declaration
/* myclass.h */
#include <QObject>
class MyClass : public QObject
{
Q_OBJECT
public:
MyClass(QObject* parent = 0);
~MyClass();
signals:
void mySignal(int);
public slots:
void mySlot();
private:
int myVariable_;
};
Implementation
/* myclass.cpp */
#include "myclass.h"
/**
* \class MyClass myclass.h
* \brief Brief description of what class provides
*
* A longer class description.
* It can be multi-line.
*/
/**
* \brief Short description of class function.
*
* Longer description of what this function does.
*/
MyClass::MyClass(QObject* parent)
: QObject(parent), myVariable_(0)
{
// ...
}
MyClass::~MyClass()
{
}
void MyClass::mySlot()
{
emit mySignal(myVariable_++);
}
Conditionals
if (foo) {
// stuff
}
else {
// stuff
}
The only time when something comes on the same line after a closing brace is at the end of a do/while loop, eg:
do {
// stuff
} while (foo);
Case statements
switch (foo) {
case bar:
// stuff
break;
default:
// stuff
}
Where to put spaces
int myVariable, secondVariable, i, j;
QObject* dummyObject;
for (int i = 0; i < 10; i++) { }
static_cast<PsiAccount*>(psiCon)->accountForName("Jabber.ru");
QString foo(const QString& str) { return str + "foo"; }
Automated Re-formatting
mblsha (one of the Psi devs) has written a blog entry on how to use a code re-formatter to get a pretty good approximation of the Psi style. It's available at http://mblsha.psi-im.org/2006/11/29/formatting-your-c-code-the-easy-way/.
Source header
All sources should begin with the standard header:
/* * filename.cpp - brief description of what file does * Copyright (C) 2003 John Anonymous * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation; either version 2 * of the License, or (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this library; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA * */
Author credits should be added in chronological order, and email addresses should not be included (they should only exist in one place — Authors and Thanks To tabs in the About Psi dialog).
Submitting your patch
- see the Submitting Patches section of the Darcs instructions to see how you can submit a recorded patch to the developers. They will review it, and get back to you with comments on how to improve your patch.
- please create (or update) a FlySpray task that describes the problems/features covered by your patch
- of course, you may also want to announce your new feature on the development mailinglist to get attention and testing from other people. That way, your patch might also be included in patched builds.
- finally, if you are able to put your patch (or your complete Darcs repository) on a website, you can also add a link to it from the Patches page.
