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 |
|
read-only (git) access |
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