Latest revision as of 13:49, 21 April 2016

Introducing yourself

We like to know who you are! If you want to start hacking on Calligra you are very welcome. Come and join us on #calligra on irc.freenode.org (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 Calligra 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 master branch. And then comes the moment you've created a nice feature or fixed a nasty bug. The first place of call is Phabricator (see also the HowTo).

After your patch gets a "Ship it!", ask a Calligra developer to commit the patch for you. Once you have shown to are comfortable putting together acceptable patches, you can apply for a Developer account. This will then allow to push your patches yourself to the Calligra codebase.

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 commit 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.
   * GIT_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.

Tools

Coding

You do not need a specific IDE to work on Calligra. 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!

CMake

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

Unit tests

Calligra 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. calligratests containing lot of good documents to test. So if you make any feature try to run calligratests 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. Calligra is built on KDE, so this is a very valuable resource.

Bug tracker

The bug tracker stores all KDE (and Calligra) 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!

English Breakfast Network

English Breakfast Network (EBN) is a website that regularly checks all KDE and Calligra 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://paste.kde.org/ 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 techbase, for instance on creating a new Flake plugin. If you are getting lost, read the Calligra architecture overview for more information. Here's a short summary:

The libraries under Calligra are:

db
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 Calligra 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 Calligra. 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.

@@ Line 1: / Line 1: @@
 = 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 koffice[email protected] and tell us who you are and what you're working on.
+We like to know who you are! If you want to start hacking on Calligra you are ''very'' welcome. Come and join us on #calligra on irc.freenode.org (or #krita if Krita grabbed your interest). Send a mail to calligra[email protected] and tell us who you are and what you're working on.
 = Coding style and licensing =
@@ Line 9: / Line 9: @@
 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.
+All files must have a license. For Calligra 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 [http://reviewboard.kde.org ReviewBoard].
+Always work against '''master''' branch. And then comes the moment you've created a nice feature or fixed a nasty bug. The first place of call is [https://phabricator.kde.org/ Phabricator] (see also the [https://techbase.kde.org/Development/Phabricator HowTo]).
+<!-- TODO Follow the [http://wiki.koffice.org/index.php?title=Contributing_a_Patch Contributing a Patch instructions] to contribute your patch.
-Follow the [http://wiki.koffice.org/index.php?title=Contributing_a_Patch 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 [http://wiki.koffice.org/index.php?title=Review_board_rules reviewboard policy], please notify the [email protected] mailing list. -->
-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 [http://wiki.koffice.org/index.php?title=Review_board_rules reviewboard policy], please notify the [email protected] mailing list.
+After your patch gets a "Ship it!", ask a Calligra developer to commit the patch for you. Once you have shown to are comfortable putting together acceptable patches, you can apply for a [[Infrastructure/Get a Contributor Account | Developer account]]. This will then allow to push your patches yourself to the Calligra codebase.
-After your patch gets a "Ship it!", you will be asked to get an svn account. Follow the [http://techbase.kde.org/Contribute/Get_a_SVN_Account techbase instructions]. Don't forget to ask the KOffice developer who said "ship it!" to sponsor you.
 == Anatomy of a Commit message ==
@@ Line 38: / Line 37: @@
 CC's to the given e-mail address.
-Some other useful svn key words:
+Some other useful commit 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.
+     * GIT_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 =
@@ Line 48: / Line 46: @@
 == 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!
+You do not need a specific IDE to work on Calligra. 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 [http://wiki.koffice.org/index.php?title=Building/Developing_With_QtCreator for instructions on using Qt Creator] and [http://wiki.koffice.org/index.php?title=Building/Developing_With_KDevelop for insructions for KDevelop]
+<!-- Check [http://wiki.koffice.org/index.php?title=Building/Developing_With_QtCreator for instructions on using Qt Creator] and [http://wiki.koffice.org/index.php?title=Building/Developing_With_KDevelop for insructions for KDevelop] -->
 == CMake ==
-[http://cmake.org CMake] is the build system for KOffice. KDE has many extensions to vanilla cmake, so there is no full manual available.
+[http://cmake.org CMake] is the build system for Calligra. 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!
+Calligra 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.
@@ Line 64: / Line 62: @@
 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.
+calligratests containing lot of good documents to test. So if you make any feature try to run calligratests so that it will ensure no breakage.
 == Valgrind and kcachegrind ==
@@ Line 82: / Line 80: @@
 === [http://techbase.kde.org 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.
+Techbase is a wiki where all the developer information about kde is stored. Calligra is built on KDE, so this is a very valuable resource.
 [http://bugs.kde.org 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!
+The bug tracker stores all KDE (and Calligra) 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!
-[http://www.svnsearch.org 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.
 [http://www.englishbreakfastnetwork.org 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.
+English Breakfast Network (EBN) is a website that regularly checks all KDE and Calligra code for common coding mistakes, documentation errors, user documentation validation and so on.
 [http://www.lxr.kde.org LXR]
@@ Line 100: / Line 94: @@
 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.
-. http://pastebin.com:
+. http://paste.kde.org/
 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 [http://techbase.kde.org/Development/Tutorials#KOffice_Plugin_Tutorials tecbase], for instance on creating a new Flake plugin. If you are getting lost, read the [http://wiki.koffice.org/index.php?title=KOffice2/Architecture KOffice architecture overview] for more information. Here's a short summary:
+There are some tutorials on [http://techbase.kde.org/Development/Tutorials#KOffice_Plugin_Tutorials techbase], for instance on creating a new Flake plugin. If you are getting lost, read the [http://community.kde.org/Calligra/Architecture Calligra architecture overview] for more information. Here's a short summary:
-The libraries under Koffice are:
+The libraries under Calligra are:
+* db
 * flake
 * kokross
@@ Line 123: / Line 118: @@
 ==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.
+Its a library which basically provides 'shapes', which contains various kinds of media. They provide Canvas Widget, on which Calligra apps are built on. Canvas can infact get mouse and keyboard controls.
 ==kokross==
@@ Line 147: / Line 142: @@
 ==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.
+One of the main libraries on Calligra. 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==