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

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

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

The localization files of calligra belong 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
===============

To update the debian/copyright file:

1. download the lcheck_ script::
   brz clone lp:~clint-fewbar/+junk/lcheck

2. execute licensecheck, from CDBS:::
   licensecheck --copyright -r . | ../../lcheck/licensecheck2dep5 > ../copyright_new

3. fix encoding errors, (some copyrights notices are in latin1 while some are
   in utf-8), a useful command could be::
   sed -i 's/\xc3\([^\xa1]\)/é\1/g;
           s/\xf6\([^\xa1]\)/ö\1/g;
           s/\xe0\([^\xa1]\)/à\1/g' debian/copyright_new

   Check the result with::
   iconv -f utf8 -t utf8 debian/copyright

4. Correct the errors (vimdiff is a great help)
   grep "License: UNKNOWN" debian/copyright_new, and correct it with the current copyright file.
   (The unknown licence are GPL-2+ according to upstream)

   remove all FIXME (FIRST change the FIXME at the beginning « Upstream-Name » and « Source »
   (sed -i '/FIXME/d' debian/copyright_new)
   add the License paragraph at the end (take it from the current copyright file)

   Pay attention to the headers, and whether new licenses has been added.

5. Append the static part (debian/copyright.tail)::
   cat debian/copyright.tail >> debian/copyright_new

Now you have a debian/copyright_new up-to-date. Check, and double check the
differences with the debian/copyright file before replacing it.

.. _lcheck: see http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=597861

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/

Tests
======

We now use autopkgtest to run the tests from calligra. To run it in a schroot::

  adt-run -B *.deb calligra_2.8.3-1.dsc --- schroot unstable-amd64-sbuild


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.

VC
---

Required by the Krita for vectorization.

already in Ubuntu: https://launchpad.net/ubuntu/+source/vc

http://code.compeng.uni-frankfurt.de/projects/vc

OpenGTL
--------

Required for Shiva based Generators and Filters

soon in Debian? http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=642208
already in Ubuntu: https://launchpad.net/ubuntu/+source/opengtl

http://www.opengtl.org

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/


LibEtonyek
------------

Apple Keynote Document Library
Required by the Stage keynote import filter

http://www.freedesktop.org/wiki/Software/libetonyek/


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:
