Translation(s): none

(!) ?Discussion

Git usage guide for Debian PHP packaging

pkg-php is now maintaining the PHP packages in a git repository. this page gives a quick overview for how to use git effectively. it has a mix of info good for those not too familiar with git as well as the more experienced. Skip to Getting Started to... get started :)

repository links

developer access

ssh://git.debian.org/git/pkg-php/php.git

read-only (http) access

http://git.debian.org/git/pkg-php/php.git

read-only (git) access

git://git.debian.org/pkg-php/php.git

gitweb web URI

http://git.debian.org/?p=pkg-php/php.git;a=summary

public branches

topic

debian branch

upstream branch

debian sid packaging

debian-sid

upstream-sid

debian lenny packaging

debian-lenny

upstream-lenny

debian etch (oldstable) packaging

debian-etch

upstream-etch

Note that there is also a bunch of PEAR packages maintained in /git/pkg-php. We would like to push others to use this repository for PEAR developments as well (see http://git.debian.org/ and look for pkg-php/ for a complete list).

Getting started

first, install required packages if you haven't already: apt-get install git-core git-buildpackage

next, clone the repository. developers with alioth access:

git clone ssh://git.debian.org/git/pkg-php/php.git

for anonymous (read only) access:

git clone http://git.debian.org/git/pkg-php/php.git

next, check out the debian and upstream branches that you intend to work with. for example, for working on unstable:

cd php
git checkout -b upstream-sid origin/upstream-sid
git checkout -b debian-sid origin/debian-sid

Making your changes

for files under ./debian, go ahead and edit them. when you're ready to prepare a changeset, add the files with git add filename, and follow up with a git commit.

It's recommended that you not make any edits to debian/changelog in the above process. first, combining fixes with changelog entries make it impossible to cleanly cherry-pick or merge fixes into other branches. secondly, we have the handy git-dch tool which streamlines the process for us anyway.

as an alternative to editing debian/changelog, try to make commit messages that follow the convention of a short one-line summary followed by paragraphs of prose. Also, be encouraged to append "Closes: #nnnnn" or "Thanks: some person" to the bottom of the commit message. This will be used by a hook in our central repo to update the bts for you automatically, as well as providing some good default entries for git dch to use to automatically generate a changelog. Example:

Fix for segmentation fault in mysql module

Include fix from upstream to prevent it from crashing when something wierd happens.

Closes: #nnnnnn

At this point you should probably test your fix :) (see below). If you're not happy with your fix, you can continue editing the files, and then amend them to your previous commit (assuming you haven't pushed yet) with git commit --amend.

when you're happy with the change, push it to the central repository:

git push

Building your package to test the changes

first, ensure that you have no uncomitted changes with git status

next, generate a "template" changelog file with git dch. this tool supports a "snapshot" mode for making a prerelease version of the changelog:

git dch -S -a

then, build a snapshot version of the package with git-buildpackage. the --git-ignore-new is to allow the uncommitted changelog:

git-buildpackage --git-ignore-new

Preparing a package for release

prepare a final version of debian/changelog. the following will remove the snapshot header from the changelog, change the distribution to "unstable", and open the changelog in your editor for final editorial review. feel free to make it look pretty, add/remove content based on what seems reasonable to present to the users, etc.

git dch -R
git commit -m 'prepare version x.y.z' debian/changelog

build a final version of the released package:

git buildpackage --git-tag

assuming nothing goes wrong (you did test, right? :] ), push the final changes to the central repo.

git push
git push --tags


CategoryGit