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

If there is any demand, please ask upstream to provide them. Please do not add
Debian-specific ones, as they will rot easily, and be only in English.

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

- Unit test files do not have a license [#]_;

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


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

Calligra forks some library to fit to their purpose.

- filters/words/msword-odf/wv2 [#]_

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

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

TODO

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

https://salsa.debian.org/qt-kde-team/extras/calligra
http://packages.qa.debian.org/c/calligra.html

.. vim:set filetype=rst:
