kafka for Debian
----------------
This package is created using a custom build system based on Makefiles
instead of the standard sbt build system used by upstream. The reason
for this is to satisfy debian policy that no internet connection should
be required during package building as well as security concers about
the downloaded JAR files by sbt

How to build this package
-------------------------

This repository is be used to build the kafka package using
git-buildpackage. Below we illustrate one of the ways this can work for
you:

* Install some mandatory packages

  $ apt-get install git-buildpackage

* And some not so mandatory but nice to have packages

  $ apt-get install pbuilder cowbuilder

Note that pbuilder/cowbuilder is not strictly required but it will save
you from installing the dependencies manually

* Create a cowbuilder environment (we assume you are building against
precise pangolin here)

  $ sudo DIST=precise git-pbuilder create --components "main universe"

* Clone the repo

  $ git clone http://gerrit.wikimedia.org/r/operations/debs/kafka
  $ cd kafka

* Build

  $ DIST=precise git-buildpackage -us -uc

or if you dont want to use git-pbuilder:

  $ git-buildpackage -us -uc --git-builder=debuild

* Grab your packages from the directory above the one your are in, unless
you have configured pbuilder otherwise

Build a new version
-------------------

* Should the current version in the repo not be enough, set upstream and
  fetch

  $ git remote add kafka http://git-wip-us.apache.org/repos/asf/kafka.git
  $ git fetch kafka

* Tag the version you want to build against

  $ git tag upstream/<VERSION> <commit-ish>

<VERSION> should be a valid upstream version according to the debian
specification:

https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version

<commit-sh> can be any upstream commit like git tag, branch or a single
commit. The best result will probably be achieved with a valid git tag
from upstream that matches the debian upstream version specs. In that
case <VERSION> == <commit-ish>

* Then update the master branch to reflect that

  $ git checkout master # Assuming you are not there already
  $ git merge upstream/<VERSION>

* Solve any potential conflicts that might arise. A very helpful way to
do this and avoid doing too much work is:

  $ git checkout --theirs -- .

This works because all of our changes are in debian/ so in any kind of
conflict the newer version from upstream should be used

* Add a new debian/changelog entry

  $ dch -i (don't forget to commit)

* And build as above

* Solve any problems that might arise and repeat the build

* Should you be happy with the result, rebuild with a new debian tag.
Just add the --git-tag argument on the previous command and a new
debian/<VERSION>-revision should be present.

* Push :-). git review might not be your best friend in this btw
Don't forget to push your new tag

* NOTE: Do not push new branches either upstream or yours unless you really
know what you are doing

Build trunk
-----------

The above procedure also works for building from trunk with a few
changes:

* You will have to come up with a <VERSION> to put in the changelog

* <commit-ish> == trunk

* Instead of

  $ git checkout master
  $ git merge upstream/<VERSION>

you do a:

  $ git checkout trunk (it should be linked to kafka/trunk)
  $ git checkout master
  $ git merge trunk

* The build is going to be a bit different since we now base it on a branch
and not a tag:

  $ DIST=precise git-buildpackage -us -uc --git-upstream-tree=branch \
--git-upstream-branch=trunk

* You will probably need to solve various issues. Some might be changed
files in trunk that have other versions in master, files that might need
to be deleted/altered by the debian package or a variety of other
issues. The kafka source tree is not the fairest of them all.
Hints that might help:

git checkout trunk -- <path> might come in handy
debian/patches will also need changes

but you will need your good sense in most cases