Calligra libs is a collection of libraries for very different functionality
with the common denominator that some Calligra applications depend on it.
Each of the libraries have a Mainpage.dox file which is used for API docs
and it should contain an overview of the library goal and scope. If you
add a class you should likely read this before deciding where it goes.

Various details can also be found here;
  http://community.kde.org/Calligra/Libs


At this point in time (early 2010) all of the libraries in here are not
guarenteed to have binary or source compatibility between releases.
However there is a strong push to make a subset of libraries become
more used outside of Calligra and thus they need to be backwards compatible
between releases. Which in effect means that we are working towards them
becoming Binary and Source (and behavior) compatible between releases.


General policies
================

All code in Calligra libs that will be released shall be licensed under the
terms of the GNU Library General Public License as published by the Free
Software Foundation; either version 2 of the License, or any later version.

All libraries shall be able to compile as the first and/or only part of Calligra.
Which effectively means anything in libs can not depend on another part of
Calligra outside of the libs.


Code submit policies
====================

For code and files in Calligra/libs we have some rules.
As Calligra is part of KDE we follow the KDE policies;
    http://techbase.kde.org/Policies
more specifically, for all of the code under calligra/libs we follow the coding style
  http://techbase.kde.org/Policies/Kdelibs_Coding_Style


Naming
======

All of Calligra libs uses so called CamelCase naming for all files in the libraries.
Example:  KoParagraphDialog.cpp
File extensions are always .cpp and .h
We prefer one class per file.  This is to make the filename match the class, which
obviously does not work if there is more then one class in the file.
When there is a private class that is not used outside the file it's ok to have it
in the same file as another class.
Private classes that should never be exported or used outside the library and should be
placed in a header file with the extension _p.h  (like KoRuler_p.h)
This makes it very obvious this file is not part of the public API of Calligra.


Namespaces and more naming
==========================

Calligra in general does not use namespaces, but uses a prefix for each class.
Application maintainers may have a slightly different rule.

The libs certainly don't use namespaces and (exported) classes in the libs use
the name prefix 'Ko'.
This allows you to see that any class that starts with 'Ko' is from the Calligra libs.
Note that this implies that the naming prefix 'Ko' is restricted to the libs, classes
outside the libs are not allowed to use it.

Futher names are
KW for Words classes
KoPA for the libs/kopageapp library
KPr for KPresenter
Kis for Krita (from KImage-shop)


Backwards compatibility for some libs
=====================================

For libraries that are going to have usage outside of Calligra they have some extra
rules to make sure they are backwards compatible between releases.
The list of libraries that this applies to is;
 * koodf
 * koplugin
 * pigment
 * flake
 * kotext

on top of the above list of guidelines there are some more for these that have
to be taken into account when modifying them or adding new code.
  http://techbase.kde.org/Policies/Library_Code_Policy
  http://techbase.kde.org/Policies/Library_Documentation_Policy

Not a rule, but often used in Calligra libs is the shared-d-pointer. As this
is a trick that is a bit tricky lets use this place to point to an excellent
example. Make sure to use when appropriate. (ask if in doubt)
  http://techbase.kde.org/Policies/Library_Code_Policy/Shared_D-Pointer_Example


Final rule, the common sense rule :)
If in doubt about any code change, post a review request for your change!