%(!) This document was generated using text2tags from INSTALL.t2t in the QGIS sources. Make your

% edits to that file and use t2t to regenerate in moinmoin %format, then paste the procedure in below.

%I have instated these changes so that we can have a single central document that contains all the

%instructions developers contributing to QGIS. This page should always reflect the most current SVN trunk build

%procedure - for release versions the CODING document in the sources will be generated according

%to the current build procedure at the time.

%Tim Sutton 2007

QgsPoint

QgsMapCanvas

QgsRasterLayer

Class member names begin with a lower case //m// and are formed using mixed case.

mMapCanvas

mCurrentExtent

Class member values should be obtained through accesssor functions. The function should be named without a //get// prefix. Accessor functions for the two private members above would be:

mapCanvas()

currentExtent()

Function names begin with a lowercase letter and are formed using mixed case. The function name should convey something about the purpose of the function.

updateMapExtent()

setUserOptions()

QGIS classes that are generated from Qt Designer (ui) files should have a //Base// suffix. This identifies the class as a generated base class.

QgsPluginMangerBase

QgsUserOptionsBase

* An optional (though highly recommended) context sensitive //Help// button that directs the user to the appropriate help page by launching their web browser

C++ implementation and header files should be have a .cpp and .h extension respectively.

Filename should be all lowercase and, in the case of classes, match the class name.

Class QgsFeatureAttribute source files are

qgsfeatureattribute.cpp and qgsfeatureattribute.h

Each source file should contain a header section patterned after the following example:

=== CVS Keyword ===

Each source file should contain the $Id$ keyword. This will be expanded by CVS to contain useful information about the file, revision, last committer, and date/time of last checkin.

Place the keyword right after the standard header/license that is found at the top of each source file:

/* $Id$ */

mapCanvas

currentExtent

Do not use generic type names that will conflict with other types. e.g. use "UnkownUnit" rather

than "Unknown"

Any text editor/IDE can be used to edit QGIS code, providing the following requirements are met.

Set your editor to emulate tabs with spaces. Tab spacing should be set to 2 spaces.

Source code should be indented to improve readability. There is a .indent.pro file in the QGIS src directory that contains the switches to be used when indenting code using the GNU indent program. If you don't use GNU indent, you should emulate these settings.

if(foo == 1)

{

// do stuff

...

}else

{

// do something else

...

}

Here are described some programming hints and tips that will hopefully reduce errors, development time, and maintenance.

If you are cut-n-pasting code, or otherwise writing the same thing more than once, consider consolidating the code

into a single function.

* make it more difficult for multiple copies to evolve differences over time, thus making it harder to understand and

maintain for others

This will help prevent programmers from accidentally using "=" when they meant to use "==", which can introduce very subtle

logic bugs. The compiler will generate an error if you accidentally use "=" instead of "==" for comparisons since constants

inherently cannot be assigned values.

Adding spaces between operators, statements, and functions makes it easier for humans to parse code.

Adding comments at the end of function, struct and class implementations makes it easier to find them later.

Consider that you're at the bottom of a source file and need to find a very long function -- without these kinds of trailing

comments you will have to page up past the body of the function to find its name. Of course this is ok if you wanted to find

the beginning of the function; but what if you were interested at code near its end? You'd have to page up and then back down

again to the desired part.

E.g.,

} // foo::bar()

Using braces for code in if/then blocks or similar code structures even for single line statements means that adding another

statement is less likely to generate broken code.

Adding code after bar() or baz() without adding enclosing braces would create broken code. Though most programmers would

naturally do that, some may forget to do so in haste.

* [Effective C++ http://www.awprofessional.com/title/0321334876], Scott Meyers

* [More Effective C++ http://www.awprofessional.com/bookstore/product.asp?isbn=020163371X&rl=1], Scott Meyers

* [Effective STL http://www.awprofessional.com/title/0201749629], Scott Meyers

* [Design Patterns http://www.awprofessional.com/title/0201634988], GoF

You can use the following commands to perform an anonymous checkout from the QGIS Subversion repository.

Note we recommend checking out the trunk (unless you are a developer or really HAVE to have the latest

changes and dont mind lots of crashing!).

You must have a subversion client installed prior to checking out the code. See the Subversion website

for more information. The Links page contains a good selection of SVN clients for various platforms.

/!\ **Note:** If you are behind a proxy server, edit your ~/subversion/servers file to specify

your proxy settings first!

/!\ **Note:** In QGIS we keep our most stable code in trunk. Periodically we will tag a release

off trunk, and then continue stabilisation and selective incorporation of new features into trunk.

See the INSTALL file in the source tree for specific instructions on building development versions.

== Documentation ==

See the Subversion book http://svnbook.red-bean.com for information on becoming a SVN master.

The complexity of the QGIS source code has increased considerably during the last years. Therefore it is hard

to anticipate the side effects that the addition of a feature will have. In the past, the QGIS project had very

long release cycles because it was a lot of work to reetablish the stability of the software system after new

features were added. To overcome these problems, QGIS switched to a development model where new features are

coded in svn branches first and merged to trunk (the main branch) when they are finished and stable. This section

describes the procedure for branching and merging in the QGIS project.

* Initial announcement on mailing list

Before starting, make an announcement on the developer mailing list to see if another developer is

already working on the same feature. Also contact the technical advisor of the project steering committee

(PSC). If the new feature requires any changes to the QGIS architecture, a request for comment (RFC) is needed.

* Create a branch

Create a new svn branch for the development of the new feature (see UsingSubversion for the svn syntax). Now

you can start developing.

* Merge from trunk regularly

It is recommended to merge the changes in trunk to the branch on a regular basis. This makes it easier to merge

the branch back to trunk later.

* Documentation on wiki

It is also recommended to document the intended changes and the current status of the work on a wiki page.

* Testing before merging back to trunk

When you are finished with the new feature and happy with the stability, make an announcement on the developer list.

Before merging back, the changes will be tested by developers and users. Binary packages (especially for OsX and Windows)

will be generated to also involve non-developers. In trac, a new Component will be opened to file tickets against.

Once there are no remaining issues left, the technical advisor of the PSC merges the changes into trunk.

We prefer that new feature developments happen out of trunk so that trunk remains in a

stable state. To create a branch use the following command:

When working in a branch you should regularly merge trunk into it so that your branch does not diverge more

than necessary. In the top level dir of your branch, first type ```svn info``` to determine the revision

numbers of your branch which will produce output something like this:

The second revision number shows the revision number of the start revision of your branch and the first the

current revision. You can do a dry run of the merge like this:

After you are happy with the changes that will be made do the merge for real like this:

There are a few guidelines that will help you to get your patches into QGIS easily, and help us

deal with the patches that are sent to use easily.

If the patch is a fix for a specific bug, please name the file with the bug number in it e.g.

**bug777fix.diff**, and attach it to the original bug report in trac (https://trac.osgeo.org/qgis/).

If the bug is an enhancement or new feature, its usually a good idea to create a ticket in

trac (https://trac.osgeo.org/qgis/) first and then attach you

This makes it easier for us to apply the patches since we don't need to navigate to a specific

place in the source tree to apply the patch. Also when I receive patches I usually evaluate them

using kompare, and having the patch from the top level dir makes this much easier. Below is an

example of you you can include multiple changed files into your patch from the top level directory:

If your improvements include new files that don't yet exist in the repository, you should indicate

to svn that they need to be added before generating your patch e.g.

QGIS developers are busy folk. We do scan the incoming patches on bug reports but sometimes we miss things.

Don't be offended or alarmed. Try to identify a developer to help you - using the ["Project Organigram"] and

contact them asking them if they can look at your patch. If you dont get any response, you can escalate your

query to one of the Project Steering Committee members (contact details also available on the ["Project Organigram"]).

QGIS is licensed under the GPL. You should make every effort to ensure you only submit patches which are

unencumbered by conflicting intellectual property rights. Also do not submit code that you are not happy to

have made available under the GPL.

Write access to QGIS source tree is by invitation. Typically when a person submits several (there is no fixed

number here) substantial patches that demonstrate basic competance and understanding of C++ and QGIS coding

conventions, one of the PSC members or other existing developers can nominate that person to the PSC for granting

of write access. The nominator should give a basic promotional paragraph of why they think that person should gain

write access. In some cases we will grant write access to non C++ developers e.g. for translators and documentors.

In these cases, the person should still have demonstrated ability to submit patches and should ideally have submtted

several substantial patches that demonstrate their understanding of modifying the code base without breaking things, etc.

Make your changes in sources. Always check that everything compiles before making any commits.

Try to be aware of possible breakages your commits may cause for people building on other

platforms and with older / newer versions of libraries.

Add files (if you added any new files). The svn status command can be used to quickly see

if you have added new files.

Files listed with ? in front are not in SVN and possibly need to be added by you:

Your editor (as defined in $EDITOR environment variable) will appear and you should make a

comment at the top of the file (above the area that says 'dont change this'. Put a

descriptive comment and rather do several small commits if the changes across a number of

files are unrelated. Conversely we prefer you to group related changes into a single commit.

Save and close in your editor. The first time you do this, you should be prompted to

put in your username and password. Just use the same ones as your trac account.

As of November 2007 we require all new features going into trunk to be accompanied with

a unit test. Initially we have limited this requirement to qgis_core, and we will extend

this requirement to other parts of the code base once people are familiar with the

procedures for unit testing explained in the sections that follow.

Unit testing is carried out using a combination of QTestLib (the Qt testing library) and

CTest (a framework for compiling and running tests as part of the CMake build process).

Lets take an overview of the process before I delve into the details:

* **There is some code you want to test**, e.g. a class or function. Extreme programming

advocates suggest that the code should not even be written yet when you start

building your tests, and then as you implement your code you can immediately validate

each new functional part you add with your test. In practive you will probably

need to write tests for pre-existing code in QGIS since we are starting with a testing

framework well after much application logic has already been implemented.

* **You create a unit test.** This happens under <QGIS Source Dir>/tests/src/core

in the case of the core lib. The test is basically a client that creates an instance

of a class and calls some methods on that class. It will check the return from each

method to make sure it matches the expected value. If any one of the calls fails,

the unit will fail.

* **You include QtTestLib macros in your test class.** This macro is processed by

the Qt meta object compiler (moc) and expands your test class into a runnable application.

* **You add a section to the CMakeLists.txt** in your tests directory that will

* **You ensure you have ENABLE_TESTING enabled in ccmake / cmakesetup.** This

* **You optionally add test data to <QGIS Source Dir>/tests/testdata** if your

test is data driven (e.g. needs to load a shapefile). These test data should be

as small as possible and wherever possible you should use the existing datasets

already there. Your tests should never modify this data in situ, but rather

may a temporary copy somewhere if needed.

* **You compile your sources and install.** Do this using normal make && (sudo)

* **You run your tests.** This is normally done simply by doing **make test**

after the make install step, though I will explain other aproaches that offer more

fine grained control over running tests.

Right with that overview in mind, I will delve into a bit of detail. I've already

done much of the configuration for you in CMake and other places in the source tree

so all you need to do are the easy bits - writing unit tests!

Creating a unit test is easy - typically you will do this by just creating a

public methods that return void. I'll use a simple test class for QgsRasterLayer

throughout the section that follows to illustrate. By convention we will name our

test with the same name as the class they are testing but prefixed with 'Test'.

So our test implementation goes in a file called testqgsrasterlayer.cpp and

the class itself will be TestQgsRasterLayer. First we add our standard copyright

banner:

Since we are combining both class declaration and implementation in a single

file the class declaration comes next. We start with our doxygen documentation.

Every test case should be properly documented. We use the doxygen **ingroup**

directive so that all the UnitTests appear as a module in the generated

Doxygen documentation. After that comes a short description of the unit test:

All our test methods are implemented as **private slots**. The QtTest framework

will sequentially call each private slot method in the test class. There are

four 'special' methods which if implemented will be called at the start of

the unit test (**initTestCase**), at the end of the unit test (**cleanupTestCase**).

Before each test method is called, the **init()** method will be called and

after each test method is called the **cleanup()** method is called. These

methods are handy in that they allow you to allocate and cleanup resources

prior to running each test, and the test unit as a whole.

// will be called before the first testfunction is executed.

void initTestCase();

// will be called after the last testfunction was executed.

void cleanupTestCase(){};

// will be called before each testfunction is executed.

void init(){};

// will be called after every testfunction.

void cleanup();

```

Then come your test methods, all of which should take **no parameters** and

should **return void**. The methods will be called in order of declaration.

I am implementing two methods here which illustrates to types of testing. In

the first case I want to generally test the various parts of the class are

working, I can use a **functional testing** approach. Once again, extreme

programmers would advocate writing these tests **before** implementing the

class. Then as you work your way through your class implementation you

iteratively run your unit tests. More and more test functions should complete

sucessfully as your class implementation work progresses, and when the whole

unit test passes, your new class is done and is now complete with a repeatable

way to validate it.

Typically your unit tests would only cover the **public** API of your

class, and normally you do not need to write tests for accessors and mutators.

If it should happen that an acccessor or mutator is not working as expected

you would normally implement a **regression** test to check for this (see

lower down).

```

//

// Functional Testing