
===============================
Debian packaging of calligra
===============================

This file aims to document the packaging of calligra for Debian. Please feel
free to improve it if necessary.

It is mainly a reminder for myself, and an help for the newcomers :)

Howto get the upstream sources?
================================

Use `uscan` utility from "devscripts" package. `uscan` downloads upstream
tarball as per "debian/watch" file and removes "Files-Excluded" as per
"debian/copyright".



Debian Packaging
=================

The upstream code is not included in Git, but only the debian/ directory.

The master branch should be for sid, and each Debian release (wheezy, etc.) has
its own branch.

To prepare a release into Debian, please remember:

- to compare current and new release tarballs and update the copyright file
- write every Debian changes in changelog
- try to fix/address when possible all the lintian warnings
- be sure about if files has been added or removed
- dch -r to prepare the changelog for an upload
- tag the release in git when we get the accepted mail
- be sure to push all the commits and tags

How to create the debian package?
==================================

I am using sbuild_ to ensure everything will be OK. The settings of sbuild is
described here:

First copy and untar the upstream tarball. rename it to calligra_VERSION.orig.tar.bz2.
Then run sbuild to build it ::

    sbuild-update -udg unstable
    sbuild -A -d unstable


.. _sbuild: http://wiki.debian.org/sbuild

Man pages
==========

Upstream doesn't provide any man page, but the Debian policy specify to have
a man page for each binary. So I created very basic page in debian/man, but
it can be improved...

I prefer to use the restructuredText_ format (.rst files), which is much more
readable. To actually creates the man pages::

    rst2man calligraauthor.rst > calligraauthor.1

.. _restructuredText: http://docutils.sourceforge.net/

Particularities
================

- Unit test files do not have a license [#]_;
- The file ./kexi/kexidb/sqlitedump/shell.c has a funny license, but we should
 assume it's the same license as SQLite3 [#]_

.. [#] From upstream, may 2013:
 “At one point, I think we had the explicit policy that unittests weren't
 going to have a license header. I don't know why... That was back in the
 KOffice days.”

.. [#] From upstream, may 2013:
 “Regarding this please assume the same license as you use with SQLite3
 since the code is based on a small tool from SQLite3. This is
 basically public domain.”


Embedded libs
==============

Calligra forks some library to fit to their purpose.

- kexi/migration/mdb [#]_
- filters/words/msword-odf/wv2 [#]_
- 3rdparty/kdgantt
- 3rdparty/kdchart

.. [#] From upstream may 2013:
 “This is not just a copy but a fork of software that was not actively
 developed for years (that might have changes in the meantime but).
 Unless volunteers come and move the modifications upsteam (what can or
 cannot be practical but I asked for that) we depend on this exact fork
 and this is a bug-for-bug type of dependency.”

.. [#] From upstream, may 2013:
 “The wv2 in Calligra is different from the one on sourceforge (which is
 pretty much dead and no longer developed), that's why wv2 in
 filters/words/msword-odf creates a library called kowv2.
 You cannot build Calligra against the sourceforge wv2.”

Missing libs
=============

Calligra could optionally use some libraries that are not yet in Debian.
I am listing them here, not to forget the day they will be in Debian.

Cauchy's M2MML
----------------

Required for the matlab/octave formula tool

https://bitbucket.org/cyrille/cauchy

Java MPXJ
----------

Required by Plan mpxj import filter

http://mpxj.sourceforge.net/

libqgit2
---------

Calligra Gemini may use libqgit2.

Dealing with bugs
==================

TODO

Useful links
==============

http://anonscm.debian.org/gitweb/?p=pkg-kde/kde-std/calligra.git;a=summary
http://packages.qa.debian.org/c/calligra.html
http://packages.qa.debian.org/c/calligra-l10n.html

.. vim:set filetype=rst:
