========================
syslog-ng Debian sources
========================

These sources are managed in a special setup in Git (see
debian/control, or debian/control.d/control.in in a fresh checkout)
that supports multiple upstream and multiple debian versions. The
debian packaging is kept separate from the rest of the sources, so
that one can easily merge between the debian packaging branches,
without having to worry about unintentionally pulling non-debian
changes from upstream.

For this reason, the debian branch (see the branch layout section
later) uses a submodule to pull in the appropriate version of
syslog-ng. Building from this setup is possible, it produces valid
debian packages. However, for source packages, one needs a little bit
more massaging, as we want to support using unmodified upstream
tarballs too. This part will be explained in a section of its own.

-------------
Branch Layout
-------------

There are two major branch families to note:

 * upstream/mirror/${MAJOR_VERSION}: This is a mirror of the upstream
   master branch of the appropriate major version of syslog-ng. No
   changes are applied to it, ever.
 * packaging/debian/${MAJOR_VERSION}: Debian packaging for the
   appropriate major version, not directly related to either upstream
   or patched branches, but pulls in a snapshot of
   patched/${MAJOR_VERSION} as a submodule.

The packaging/debian/${MAJOR_VERSION} branch has a submodule that
points to the corresponding syslog-ng tree, whether patched or
pristine upstream.

Furthermore, a couple of other branches may appear and disappear over
time, that are part of the normal development work flow:

 * feature/${MAJOR_VERSION}/${NAME}: Each feature developed is done on
   a separate branch, and sent upstream as such. These can be picked
   onto the appropriate patched branch.
 * hotfix/${MAJOR_VERSION}/${NAME}: Bugfixes and the like for the
   appropriate version, that are also sent upstream. Similarly to
   feature branches, there can be picked onto the appropriate patched
   branch.
 * merge-queue/${MAJOR_VERSION}: Patched proposed for mergint into the
   relevant major version, pending review.
 * sandbox/${MAJOR_VERSION}: Sandboxes for experimental patches
   mostly. These branches are often rebased, and they should not be
   relied upon.

--------------------
Development workflow
--------------------

To update the package, the following workflow should be kept:

Upgrading to a new upstream version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Pull the upstream changes as-is onto the appropriate upstream
  branch. (such as upstream/mirror/3.3)
* If all patches were applied upstream, update the submodule on the
  packaging branch (packaging/debian/3.3).

  If not, create a separate branch, and apply any necessary patches
  there, and set the submodule to point there.
* Run debian/tools/bootstrap.sh with selected flags (see below), and
  make sure it did the right thing.

  The bootstrap.sh tool generates debian/control, from
  debian/control.d/control.in, and allows one to selectively enable or
  disable features in a source package. As of this writing, the only
  optional feature is "systemd".

  If enabled (which is the default), libsystemd-dev and
  dh-systemd will be added to Build-Depends. To disable the feature,
  pass an empty string as an argument to the bootstrap script.

  Once verified, commit the changes to git. The files generated by the
  scripts are NOT stored in git, one is expected to bootstrap the
  sources by running debian/tools/bootstrap.sh.

Selectively applying upstream fixes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Pull the upstream changes as-is onto the upstream/mirror branch.
* cherry-pick the appropriate fixes to a separate branch.
* Update the syslog-ng submodule of the debian packaging branch.

Debian-specific changes
~~~~~~~~~~~~~~~~~~~~~~~

Debian packaging specific changes should directly go to the debian
packaging branch.

-----------------
Building from git
-----------------

To build the package from git, one will first need to initialize it,
by pulling in the appropriate submodules, and generating a few
files. This can be accomplished by running the
debian/tools/bootstrap.sh script.

---------------------
Exporting the sources
---------------------

The orig.tar.xz can be generated by debian/rules get-orig-source. The
packaging does not use the upstream tarballs, as it is built directly
from git.

However, the tarball generated by get-orig-source (similarly to
upstream packages) does not reside in a subdirectory, so one needs to
do some extra work to make the tree ready for a sourceful build:
export it so that debian/ is applied on top of the patched branch.

Once done, the tree is ready to be built.

With the above workflow, the patches on the patched branch will get
flattened during build into a single debian/patches/debian-changes
patch. If one wants to make modifications, that should be done in git,
not with the exported sources.

The debian/tools/export-source.sh tool automates the bulk of the
above: it sets up a directory, where the debian/ dir is merged into
the patched sources.

 -- Gergely Nagy <algernon@madhouse-project.org>, Tue,  2 Jul 2013 14:14:57 +0200
