Introduction

Here's a small howto on how to work with the pkg-iproute Collaborative Maintenance repository on Alioth. This repository is the base for the "iproute", "iproute-dev" and "iproute-doc" packages (src:iproute) found in Debian (and Ubuntu).

Working with pkg-iproute collab-maint repository

Since v2.6.35 a.k.a. snapshot 20100804, the repository has been switched to work more like common git-buildpackage conventions. We now import the real upstream tarball, since we can now work with bz2 orig tarballs since debian source format 3.0.

The new style goes something like this:

checking out and building the repository

importing a new upstream release

patching















The instructions below this line does not apply since >= v2.6.35 (20100804)

1. Setting up a working repository.

1.1 Checking out the Alioth pkg-iproute repo.

$ cd /foobar

$ git clone git://git.debian.org/git/collab-maint/pkg-iproute.git

$ cd pkg-iproute

(Note: debian-developers and Alioth guests who intend to push things back into the repository should use ssh://username@ instead of git://.)

1.2 Creating local branches for Alioth equivalent.

$ git checkout -b patches origin/patches

$ git checkout -b upstream origin/upstream

$ git remote add upstream-repo git://git.kernel.org/pub/scm/linux/kernel/git/shemminger/iproute2.git

2. Making changes...

2.1 ... to debian packaging.

# check out the debian (master) branch and make sure we are clean and tidy.

$ git checkout -f master

$ git clean -f -d

# make changes.

$ sensible-editor debian/some-file

# review changes.

$ git status

# if status says there are untracked files, which you want git to track, simply add them with "git add new-file" and try git status again.

$ git diff

# commit changes and write commit message.

$ git commit debian/some-file

(Note: if you want to commit all changes and don't want to specify files, use git commit -a)

2.2 ... to something that should go upstream.

# create patch.

$ git checkout -f patches

$ git clean -f -d

$ sensible-editor some-file

$ git status

# if status says there are untracked files, which you want git to track, simply add them with "git add new-file" and try git status again.

$ git diff

$ git commit some-file

# apply it to debian branch.

$ git checkout -f master

$ git clean -f -d

$ git merge patches

3. New upstream release.

3.1 Updating

$ git fetch upstream-repo

(Optional step: mail upstream asking him to push out the tag he forgot to make public.)

# update the "upstream" branch to contain the stuff that should go into orig.tar.gz.

$ git checkout -f upstream

$ git clean -f -d

$ git merge some-tag

# update patches.

$ git checkout -f patches

$ git clean -f -d

$ git rebase -i upstream

(Optional step: resolve conflicts and commit or git rebase --continue to drop.)

# update debian package.

$ git checkout -f master

$ git clean -f -d

$ git merge patches

3.2 Publishing.

If you have rebased the patches branch you'll need to delete Alioths patches branch, since the rebased patches branch is basically a new branch with the same name. They will clash if you have two different branches with the same name.

To delete a remote branch just push an empty branch into it. (syntax: <local>:<remote>).

$ git push origin :patches

Then you can push out your new patches branch:

$ git push origin patches:patches

After publishing a rebased patches branch, you should tell the other people who might have a local patches branch about this! A suggestion is to send a short note to the "Debian iproute maintainers" address which is currently <ah-iproute (at) debian.org> saying you have rebased and possibly also add a short summary of what other changes you've made.

Now you're free to push out your stuff....

$ git push origin

4. Other common tasks.

4.1 Commit messages and debian changelog.

It's important to write good commit messages. This is how to later find out *why* a change was made when you've forgot all about it (don't write *what* has been changed, that's visible in the commit diff.)

The first line in the commit message is a short description of the commit. This is what will show up in the "shortlog" and also will be imported into the debian/changelog by the git-dch tool.

The git-dch tool can be really useful for updating the debian changelog. Make sure to pass --since=<commit-id> from the last commit that has the description "Update debian/changelog". If you've merged a new upstream release, use the commit-id from the very last commit since you don't want to import every upstream commit message into the debian changelog.

Finally, don't forget to commit the changes you've made to the debian changelog:

$ git commit -m "Update debian/changelog" debian/changelog

4.2 Fetching updates.

If you have received an email saying that someone has rebased the patches branch, you need to delete your local copy of it and fetch the new version on Alioth.

$ git branch -d patches

(If you have been keeping patches for yourself which you haven't pushed out to Alioth, then that's bad for you. You'll need to export the commits to regular patches, save them somewhere, still delete your branch, pull the new one in, apply the patches again..... Simply: make sure to push out your changes. It'll make life easier for everyone, yourself included.)

Other people might have been pushing updates to the alioth repository since you cloned it. To fetch new changes simply do:

$ git pull origin

5. Building packages from the (local) repository.

$ git-buildpackage

6. Making a release.

$ git checkout -f master

$ git clean -f -d

# switch from "UNRELEASED" to unstable, and remove possible banners in the debian changelog.

$ sensible-editor debian/changelog

# commit.

$ git commit -m "Update debian/changelog" debian/changelog

# build and tag

$ git-buildpackage --git-tag

# push out changes and new tag(s) to Alioth.

$ git push origin $ git push --tags origin

7. See also