borgbackup for Debian - information regarding the packaging
===========================================================



How upstream sources end up in the Debian source package
--------------------------------------------------------

The borgbackup source is managed in a GIT repository by upstream. Their
release process publishes tar-balls on [1] and PyPi packages on [2]. While
the former corresponds exactly to signed tags from the upstream
repository, the latter are created and gpg-signed by the upstream
maintainer and include several files which are created during a release
build and are not contained in the upstream GIT repo (mainly
Cython-generated *.c files, see below).

This Debian source package is maintained in a GIT repo as well, however it
is not a direct clone of the upstream sources. Instead we use
  `gbp import-orig --upstream-vcs-tag=TAG`
to import the tar-balls published on [2]. This allows for working with
official releases as advertised in the upstream documentation, while
maintaining the link to upstream version control.

[1] http://github.com/borgbackup/borg/releases
[2] https://pypi.python.org/pypi/borgbackup/



Building the package
--------------------

Please note that a simple "debuild" does not necessary build the
Debian package correctly, *when called in a git clone*.

This is because upstream uses python-setuptools-scm to generate
version numbers, which can produce unexpected results when parsing
the debian tags.  If called outside a git clone, it will fall back
to reading the (upstream-provided) metadata files, which works fine.

It is therefore recommended to build from outside a git clone.

Git-buildpackage includes an "export" feature which will transfer
the files to a scratchpad directory and call debuild/cowbuilder in
that directory; read gbp-buildpackage(1) for details.  The included
debian/gbp.conf file by default activates exporting and uses
"../build-dir/" as a scratchpad.

tl,dr:
1. use "gbp buildpackage" instead of debuild
2. to incrementally work on changes, use a command like
    git add -u && gbp buildpackage --git-ignore-new --git-export=INDEX



Auto-generated files that are included in upstream tarball
----------------------------------------------------------

The upstream tarball contains some files that can be automatically
generated, mainly the Cython-processed *.c files.

After discussion at #792096, it was agreed that we should rebuild
the cython *.c files during build.  This is currently done by deleting
them using the debian/clean file, and letting the upstream build-system
automatically regenerate them as needed.

When updating the package, please check whether files have been added
or removed from this set and update debian/clean accordingly.



Manpage generation
------------------

The manpage included in this package is created using the upstream Sphinx
build system, which includes a "make man" command.

See also upstream issue 208 about manpages:
https://github.com/borgbackup/borg/issues/208



Python3-msgpack dependency
--------------------------

When updating the package, please also check whether the explicitly
given versioned runtime dependency on python3-msgpack is still
necessary.

When building without it, python3:Depends may only pick up a non-versioned
dependency for the binary package, resulting in an installable, yet not
runnable binary package in a backport situation.
(At the time of writing, stable/jessie only has 0.4.2)



Priority extra because of lz4 dependency
----------------------------------------

Keep an eye on liblz4 (source package lz4), which is currently (Jan 2016)
priority extra.  If it gets increased to optional, we can re-include
borgbackup in the optional set.
