The Git Repository
==================

Git allows repositories to have a number of formats and a number of ways
of working so there is a need to document the working practice.
What follows is largely drawn from the Debian Perl Group's git guide:
http://pkg-perl.alioth.debian.org/git.html .

The repository can be browsed at:
http://anonscm.debian.org/gitweb/?p=collab-maint/lsof.git;a=summary

The latest version of this file can be found at:
http://anonscm.debian.org/gitweb/?p=collab-maint/lsof.git;a=blob_plain;f=debian/README.source;hb=HEAD

A key point is that using a repository like this means that there is no
need for using mentors or any other upload site.  We just use the 
repository to communicate.

Layout
------
The repository has three branches: "master", "upstream" and "pristine-tar".
You always work in "master" and the other branches are maintained behind the
scenes by the various tools. The "upstream" branch represents the contents
of the "orig" tarball - that is after the non-DFSG source has been removed.
The "pristine-tar" branch contains housekeeping data in a binary format.

So the "upstream" branch never contains the debian directory. Also at the point
of writing the upstream branch contains unpatched files (e.g. scripts/00README),
but the master branch contains patched files. However when we switch to the
modern package layout, the Debian Perl Group practice would be for the master 
branch to also contain unpatched files with the patches in quilt format in
debian/patches. This practice works well with dpkg-buildpackage but not from
what I have seen with git-buildpackage. So beware.

Also note that there are two parallel series of tags: one for the upstream code and
one for the package as a whole.

Requirements
------------
First of all you need to register an alioth account:
https://alioth.debian.org/account/register.php .

Then you need to join the collab-maint:
https://alioth.debian.org/projects/collaba-maint/

To work on this package you need the following packages:
    git-buildpackage
    pristine-tar
    pbuilder (or sbuild or cowbuilder)

Initial checkout
----------------
This command creates an "lsof" directory with all the appropriate git trimmings:
$ gbp-clone --all --pristine-tar ssh://git.debian.org/git/collab-maint/lsof.git

Upgrading to a new upstream source
----------------------------------
I would like to be able to say that the first step is usually:
$ git-import-orig --uscan --pristine-tar  # DO NOT DO THIS!

However we are suffering under #635920. It may be that the latest release
has no non-DFSG material in which case we can move in that direction.
In the meantime the sequence seems to be:

$ uscan --verbose 
$ git fetch origin upstream:upstream pristine-tar:pristine-tar
$ git-import-orig --pristine-tar ../lsof_X_orig.tar.gz

Assuming that this is a clean upgrade requiring no other changes, you 
do the following:

$ dch -vX
[ Make sure that the debian/changelog file is okay.]
$ dch -r        # Updates the timestamp and sets the distribution to unstable
$ debcommit -a -r # Checks in the code and takes the git commit messages from the changelog
$ git push 
$ git push --tag

That is as much as you can do as a non-DD.

Other changes
-------------
It is a good idea to use the "dch" command to change the changelog. It does
the following (at least if done right which I am not actually 100% sure about. ;-( )
- Sets the distribution to UNRELEASED showing that the package is not yet ready.
With the -r option it sets it "unstable". This is about communicating the 
status of the package in a clear way.
- It updates the timestamp.
- It handles the situation where two people are working on different aspects of the
package.

Having made a change and described it in the changelog you do
$ debcommit -a
This checks the code in taking the git comment from the changelog.

To push the code upto the server do
$ git push

I like this flow of debian/changelog driving the git comments. It feels natural 
to me. However others swear by the alternative git comments driving the changelog
which feels unnatural to me - checkout the "git-dch" command.

If you need to make a change but there can be no corresponding changelog
entry, do:
$ git commit -a

Also sometimes you need to add files:
$ git add [file]

And to check on the status of your working area:
$ git status

On a separate but related issue, it clearly is good practice to try to
maintain a 1-1 correspondence between changes and commits. It would
make it easier to backport a specific fix. However this is an ideal
and noone should ever make an issue of this.

Finishing off a release
-----------------------
Again when a release is ready for review (and after you have run 
all the lintian and pbuilder checks) you indicate its readiness with:
$ dch -r
$ debcommit -a -r
$ git push
$ git push --tag
