drbd-doc packaging information
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. General information
——————————————————————
The drbd-doc source combines the source from two distinct upstream locations:

 • The DRBD User's Guide[1]
 • The "makedoc" documentation build system[2]

Makedoc is an autotools-based asciidoc build system written by LINBIT. Since it
is exclusively used by the drbd documentation, we decided not to ship it as a
separate package, but instead embed it into the drbd-doc source using the 3.0
source format's multiple tarball support.


2. Versioning scheme
————————————————————
Neither the User's Guide, nor makedoc have actual versions, so we use a custom
scheme of <drbd_minor_version>~<guide_date>-<debian_revision>, e.g.
8.4~20130416-1.


3. Git repository layout
————————————————————————
The packaging is maintained using a git repository at

http://anonscm.debian.org/gitweb/?p=debian-ha/drbd-doc.git

The repository has a git-buildpackage compatible layout with the following
branches:

 • master: the branch the drbd-doc package is built from.

 • upstream/doc: a branch tracking upstream's drbd-documentation git
                 repository[1].

 • upstream/makedoc: a branch tracking upstream's makedoc git repository[2],
                     with all upstream source moved to makedoc/.


4. git-buildpackage compatibility
—————————————————————————————————
The package can be built using git-buildpackage, as long as the upstream
tarballs are found in the parent directory. Note that gbp does not (yet? see
#561071) support multiple upstream branches, so the orig tarballs have to be
generated manually using pristine-tar checkout.


5. Importing a new upstream version
———————————————————————————————————
To generate a package from a new upstream versions, follow these steps:

  ₁ Pull the upstream sources in upstream/doc and upstream/makedoc

  ₂ Tag the releases in one or both upstream branches if applicable, e.g.
     git tag -s doc/20130416 upstream/doc

  ₃ Merge the tags to master:
     git merge doc/20130416

  ₄ Generate *both* orig tarballs:
     git archive --format=tar --prefix=drbd-doc-20130416/ doc/20130416 \
         | xz > ../drbd-doc_20130416.orig.tar.xz
     git archive --format=tar makedoc/20120726 \
         | xz > ../drbd-doc_20130416.orig-makedoc.tar.xz

  ₅ Commit *both* tarballs to pristine-tar, specifying also the tag they were
    generated from:
     pristine-tar commit ../drbd-doc_8.4\~20130416.orig.tar.xz doc/20130416
     pristine-tar commit ../drbd-doc_8.4\~20130416.orig-makedoc.tar.xz \
         makedoc/20120726

[1] git://git.drbd.org/drbd-documentation.git
[2] https://github.com/fghaas/makedoc.git

 -- Apollon Oikonomopoulos <apoikos@debian.org>  Mon, 07 Jul 2014 12:06:29 +0300
