
===============================
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 ?
=================================

Upstream provide an archive for each release, accessible on the FTP_ of KDE:


.. _FTP: ftp://ftp.kde.org/pub/kde/stable/calligra-latest/

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, don't forget:

- to update the copyright file
- write every debian changes on the changelog.
- correct 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

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

I am using sbuild_ to ensure everything will be OK. The settings of sbuild is describe 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

Localization files
====================

The localization files of calligra belongs to the source package calligra-l10n.

To package it, just copy each calligra-l10n-LANG.tar.bz2 from the FTP, and then run sbuild.

Copyright file
===============

Each subdirectory of the upstream source has a paragraph in the Copyright File.

To update it, I am using a custom script based on copyright_helper_

TODO finish the script to have an automatic way of updating the copyright file.

.. _copyright_helper: git://anonscm.debian.org/users/modax/copyright-helper.git

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
================

- Calligra forks kexi/migration/mdb [#]_ and filters/words/msword-odf/wv2/ [#]_ for their purpose;
- Unit test files does 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:
 “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.”

.. [#] 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.”

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

TODO

Usefull 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:
