Introducing yourself

We like to know who you are! If you want to start hacking on KOffice you are very welcome. Come and join us on #koffice on irc.freenode.org (or #kpresenter if you are mainly interested in kpresenter, or #krita if Krita grabbed your interest). Send a mail to [email protected] and tell us who you are and what you're working on.

Coding style and licensing

Be aware of the KDE-wide set of policies: | Policies for Developers. If anythinghere confuses you, don't hesitate to ask.

Please follow the [ coding style guidelines]! Change the configuration of your editor if necessary. Some editors can have per-project settings.

All files must have a license. For KOffice you can use LGPL v2+ (all libraries, most aplications, most plugins) or GPL v2+. For some plugins, LGPL version 2.1 (no plus) is acceptable as well. Your full, real name must be in the license header.

Committing stuff

Always work against trunk! And then comes the moment you've created a nice feature or fixed a nasty bug. The first place of call is ReviewBoard.

Follow the Contributing a Patch instructions to contribute your patch.

You will get some reviews, asking you to change things or telling you to "Ship it!". If you feel that the reviews are not according to the reviewboard policy, please notify the [email protected] mailing list.

After your patch gets a "Ship it!", you will be asked to get an svn account. Follow the techbase instructions. Don't forget to ask the KOffice developer who said "ship it!" to sponsor you.

Anatomy of a Commit message

Title: A one line description about the commit. Make sure that the title is relevant so that searching later becomes easy.
blank line
Description: Detailed description about the commit.

There are a couple of useful tags:

BUG: <bugnumber> Marks the bug as fixed by CC'ing the commit message to <bugnumber>[email protected]. This keyword will also be used to automatically extract entries for the release changelog.

CCBUG: <bugnumber> CC's to the bugreport by sending mail to <bugnumber>@bugs.kde.org

CCMAIL: <email-address> CC's to the given e-mail address.

Some other useful svn key words:

   * GUI: Indicates a user visible change in the user interface. This is used to make the documentation team aware of such changes.This keyword can appear anywhere on a line.
   * SVN_SILENT Marks the commit message "silent" by adding "(silent)" to the subject of the mail to allow filtering out trivial commits. Use this tag carefully and only for really uninteresting, uncontroversial commits.
   * SVN_MERGE Special keyword for people that use the svnmerge script. Marks the commit message as being a merge commit by adding "(merge)" to the subject of the mail. This way receivers can filter out mails that are caused by merging the same patch from one branch to another branch. Reviews of those mails is usually not needed. This keyword filters out the endless property changes used by this script.

Tools

Coding

You do not need a specific IDE to work on KOffice. Some IDE's people use are KDevelop, Qt Creator, Eclipse. Others use plain editors: Kate, Kwrite, vi(m), Emacs. It's a matter of your personal preference!

Check for instructions on using Qt Creator and for insructions for KDevelop

CMake

CMake is the build system for KOffice. KDE has many extensions to vanilla cmake, so there is no full manual available.

Unit tests

KOffice has a suite of nearly two hundred unittests. Unittests are run regularly to ensure that we have a minimum of regressions. After writing code, you should always run the relevant unittests!

To be able to run unit tests, you need to explicitely enable them in the build configuration. To do so, set the KDE4_BUILD_TESTS variable to "ON", either by issuing the command cmake -DKDE4_BUILD_TESTS=ON, or by running ccmake .. Both commands must be executed in the build directory. You can then run the test with make test, or individually in the tests directories. It is recommended to call make install before running tests.

If you fix any bug or any feature it should be accompained by ideally unit test cases. kofficetests containing lot of good documents to test. So if you make any feature try to run kofficetests so that it will ensure no breakage.

Valgrind and kcachegrind

Valgrind is used for three things: check errors in memory handling (memory leaks and accessing deleted memory), analyzing memory consumption and analyzing the performance of an application.

Memory errors: valgrind --tool=memcheck --error-limit=no app args
Memory consumption: valgrind --tool=massif app args
Performance profiling: valgrind --tool=callgrind app args

At program termination, a file callgrind.out.pid will be generated, which can be loaded into KCachegrind.

More information at using valgring

Useful websites

Techbase

Techbase is a wiki where all the developer information about kde is stored. KOffice is built on KDE, so this is a very valuable resource.

Bug tracker

The bug tracker stores all KDE (and KOffice) bugs and wishes users report. If you feel bored, you can trawl through bugs.kde.org and see whether there's a bug that appeals to you!

svnsearch

SVNSearch is a tool for exploring the development history of KOffice. You can use it to check when something was done, why and by whom. Or who is the main person responsible for a particular piece of code.

English Breakfast Network

English Breakfast Network (EBN) is a website that regularly checks all KDE and KOfice code for common coding mistakes, documentation errors, user documentation validation and so on.

LXR

LXR allows users and developers to browse the KDE source code complete with cross-references. This is particularly useful if you want to figure out where some code is used.

6. http://pastebin.com: If you have more than one line of code to share with someone on the IRC or any other place do use this website. Here you can post your code and share the link on the IRC. Any one on the IRC can then access this link to view your code.

Hacking

There are some tutorials on tecbase, for instance on creating a new Flake plugin. If you are getting lost, read the KOffice architecture overview for more information. Here's a short summary:

The libraries under Koffice are:

flake
kokross
kopageapp
koplugin
koproperty
koreport
kotext
main
odf
pigment
widgets

flake

Its a library which basically provides 'shapes', which contains various kinds of media. They provide Canvas Widget, on which Koffice apps are built on. Canvas can infact get mouse and keyboard controls.

kokross

It is used mainly for scripting. It supports various scripting languages. It is mainly GUI based.

kopageapp

Used for Single Page based application. This means that, the documents can indeed have multiple pages, but not continuing from one page to another. Used in Kivio and Kpresenter.

koplugin

It is used for loading the plugins. Pigment depends on this.

koproperty

This library is used to handle property lists or key listing such as the properties of view, editors and so on.

koreport

It is used to produce formatted reports. Used in kexi and kplato

kotext

One of the main libraries on koffice. It is used in loading the text, to do various text handling, parsing of files, handling the text layout, gives layout API definitions,etc.

main

Contains the base classes for applications, documents and views. Supports filter chaining and exporting and importing filters.

odf

Another important library. ODF stands for Open Document Format. It is an XML based format. Supports various kinds of documents, spreadsheets, presentations,etc.

An odf file is basically a zip archive with filter specific content.

It also handles validation and encryption.

pigment:

It is used in color management and handling. It provides various Color Profiles.

widgets:

Used in handling widgets, such as progress bar updates, sliders, switching between the sheets,etc.