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

git@salsa.debian.org:php-team/php.git

read-only (https) access

https://salsa.debian.org/php-team/php

read-only (git) access

https://salsa.debian.org/php-team/php.git

public branches

topic

debian branch

upstream branch

PHP 7.4 packaging

master-7.4

upstream-7.4

PHP 7.3 packaging

master-7.3

upstream-7.3

PHP 7.2 packaging

master-7.2

upstream-7.2

PHP 7.1 packaging

master-7.1

upstream-7.1

PHP 7.0 packaging

master-7.0

upstream-7.0

PHP 5.6 packaging

master-5.6

upstream-5.6

Note that there is also a bunch of PEAR packages maintained in https://salsa.debian.org/php-team/pecl

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:

gbp clone git@salsa.debian.org:php-team/php.git

for anonymous (read only) access:

gbp clone https://salsa.debian.org/php-team/php.git

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

cd php
git checkout -b upstream-7.4 origin/upstream-7.4
git checkout -b pristine-tar origin/pristine-tar
git checkout -b master-7.4 origin/master-7.4

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 -a -c

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 origin : --follow-tags


CategoryGit