=head1 NAME git - Debian Perl Group Packaging and Git Guide =head1 DESCRIPTION This guide describes the procedures that the Debian Perl Group contributors use to maintain packages in the Git repositories on salsa.debian.org. It covers the following tasks: =over 4 =item * Creating a new Debian package from a Perl module. =item * Updating the repository for a package. =item * Building a package and preparing it for upload. =item * Uploading a package to the Debian archive. =item * Upgrading a package to a new upstream release. =item * Getting the source for all packages with L. =back The guide is a work in progress. Different people tend to do things in different ways. If your way diverges, you may want to document it here so that others can benefit. Please send any comments or ideas to Edebian-perl@lists.debian.orgE. For a more general guide to Git, see the Git User's Manual at L. For an introduction to salsa.debian.org see L. =head1 The Tools First, you need to install B. It contains a collection of scripts useful for the day to day work. Each group package has its own Git repository. If you are working with multiple packages, then you will probably want to use L to manage the multiple Git repos involved. For this workflow, you'll need the helper perl scripts in the C repository. Check out C repository with $ cd $HOME/src $ git clone git@salsa.debian.org:perl-team/modules/meta.git At this point it is a good time to configure L. Decide where you want to store the cloned repositories, and tell I about it. For example: $ mkdir $HOME/src/pkg-perl/packages $ echo "DPT_PACKAGES=$HOME/src/pkg-perl/packages" >> $HOME/.config/dpt.conf As outlined in L, you'll also need to add a private token for salsa. If you don't have one, or if you want a dedicated one for I, create it on L (with the B and B scopes), and add it to your configuration: $ echo "DPT_SALSA_PRIVATE_TOKEN=obviously-This-isnt-a-real-1" >> $HOME/.config/dpt.conf I the C repository should be cloned in such a way that it contains the F directory created above. =head1 Packaging walkthrough =head2 starting a new package =head3 a) the "all-in-one" approach When called with C<--pkg-perl> options, C populates a Git repository with C, C and C branches, and sets up an C remote pointing to Salsa. C creates and configures a new project on salsa and pushes the local repository there. $ dh-make-perl [option] --pkg-perl --cpan Foo $ dpt salsa pushrepo =head3 b) alternative: adding Git stuff manually B imports the source of a package into the Git repository. It operates on the C<.dsc> file and the associated source files. Example of starting a new package from scratch: $ mkdir libfoo-perl $ cd libfoo-perl $ git init $ gbp import-dsc --pristine-tar ../libfoo-perl_1.23-1.dsc If the package is already in Debian and you want to add a bit of history to the repository, repeat the last command for all C<.dsc> files you have, in incremental version order. Alternatively you could use B. Note that L has many options to make your life easier. B: L adds a C tag. This one should not be pushed for new packages (but deleted, and later created after the first upload). - Since version 0.6.0, L has a switch B<--skip-debian-tag> to avoid creating the C tag. =head3 c) more alternatives An alternative for a new package, as described in L ("Importing a package" -E "If you're instead starting from scratch ..."), is to create a new empty repository and then use L, L and L. If your package does not have a .dsc file you can use (running from the new empty repository): $ gbp import-orig --pristine-tar ../libfoo-perl_1.23.orig.tar.gz =head2 working with existing packages =head3 cloning a single package repository $ dpt checkout libfoo-perl This will go to F<$DPT_PACKAGES/libfoo-perl> and invoke L. If the directory does not exist, L is used to create the initial clone. You could do it manually, of course: $ cd $HOME/src/pkg-perl/packages $ gbp clone --all --pristine-tar git@salsa.debian.org:perl-team/modules/packages/libfoo-perl.git =head3 tracking all repositories with L Add the following to your F<~/.mrconfig>, creating it if needed: [src/pkg-perl] chain = true checkout = git clone git@salsa.debian.org:perl-team/modules/meta.git pkg-perl Notes: =over 4 =item * The destination path is relative to and has to be in a subdirectory of the F<.mrconfig> file; i.e. [/tmp/foobar] in F<~/.mrconfig> is not supported. =item * The last part of the path has to be the same as the target of the clone command (in this example: F). =back You then need to explicitly trust F<~/src/pkg-perl/.mrconfig>, by adding it to F<~/.mrtrust>, otherwise the C feature will be disabled for security reasons. Now run B to clone the C repository, which contains another F<.mrconfig> with some features and some helper scripts. A second invocation of B clones all the repositories listed in C's F<.mrconfig>, i.e. all git repositories in L. For the adventurous: mr --trust-all bootstrap https://salsa.debian.org/perl-team/modules/meta/raw/master/.mrconfig does mostly the same, except that the authenticity and integrity of the initial F<.mrconfig> is not checked in any way. From here on, updating all repositories is a simple C. You can use the C<-j/--jobs> option to update several repositories in parallel. B Before B 0.46 it was necessary to run B manually before C could detect that a repository needs updating. As this command may take several minutes to complete, some people prefer to run it daily from cron instead of interactively, or to put it into the meta.git section in F<~/.mrconfig> (or in some other place, actually): [src/pkg-perl] chain = true checkout = git clone git@salsa.debian.org:perl-team/modules/meta.git pkg-perl include = echo "Updating hashes of perl-team repositories ..." >&2 && dpt salsa githashes -j $(nproc) || true =head2 repository layout We're using the typical B branch layout: Upstream sources are kept (in plain, uncompressed form) in the C branch. The data needed to regenerate original source tarballs from the C branch is kept with the help of L in the C branch. Upstream sources are merged with Debian-specific changes in the C branch, which is the usual place to work in. From this point on, work on the package normally. Some prefer to update F with each commit, others leave this to the L tool at package release time. In case you use L for the changelog entries, don't forget to use it when you stop working on the package. =head2 pushing to salsa.debian.org I read this section. The C repositories use some infrastructure that is set-up by the below methods. Non-C methods such as C will not set up this infrastructure. The first time you push, use: $ dpt salsa pushrepo This creates and sets up the repository on Salsa, and then pushes the local repository. From then on, use C as usual or use L for committing, which also pushes the changes to the original repository on Salsa, mimicking the subversion commit behaviour at the expense of the ability to make amends, squashes and splits of commits (you still have to push any non-active branches or tags via C). -- Note that L's feature to push-on-commit is turned off if you use our F<.mrconfig> from the C repository as described above. =head2 building the package Use your favourite way of building the Debian package. If the source tarball is not in F<../>, check it out from the pristine-tar info (this is not needed if you use L with the settings mentioned in L below): $ pristine-orig Or, if you want a version which is not on the top of F, or you simply like to type a lot: $ pristine-tar checkout ../libfoo-bar-perl_1.23_orig.tar.gz This requires that you have the C branch current (e.g. via C or L). After uploading, tag the release. The easiest way is to use L or L: $ debcommit -a -r $ gbp tag Push the result afterwards: $ dpt push or $ git push origin master upstream pristine-tar $ git push --tags or $ gbp push =head2 uploading a package Only official developers have permission to upload packages to the archive (see the Maintainers' Guide in L). In case you aren't an official developer, change the release from C to C (using C) and push the changes. The package will then be listed in the I section in PET and someone else will perform the upload on your behalf (or reset it back to C and add C items to the changelog, which you should watch out for and fix). B: PET is not functional anymore after the move to salsa.debian.org. =head2 upgrading to a new upstream release First make sure that the local repository is up to date, for example using L. If the Debian package has a debian/watch file you can use the L tool to check for the latest upstream release and download it. =head3 importing the new upstream sources =head4 using dpt import-orig L is a wrapper around L which also tracks the upstream git repository. This is the simplest way to import a new upstream release: $ dpt import-orig =head4 using gbp import-orig --uscan L, when used with its C<--uscan> option, acts as a frontend for C: $ gbp import-orig --uscan --pristine-tar Basically, this command downloads the latest tarball and imports it into the Git repository: the new sources are imported into the C branch, tarball data is put into the C branch, the upstream release is tagged and finally that tag is merged into the C branch. =head4 using plain uscan $ uscan This downloads the latest tarball in F<../> and symlinks it to the proper .orig.tar.gz (you can use the C<--rename> options of uscan to directly rename the tarball without symlinking). If the watch file is not present you have to download the tarball manually. Then import the new upstream release in the git repository: $ git fetch origin upstream:upstream pristine-tar:pristine-tar $ gbp import-orig --pristine-tar ../libfoo-bar-perl_2.00_orig.tar.gz =head3 last steps (Not needed when using L.) Create a new F stanza about the new upstream release: $ dch -v2.00 'New upstream release' This can be automated by the following configuration in F<~/.gbp.conf>: [import-orig] # run hook after the import: postimport = gbp dch -N%(version)s -S -a --debian-branch=$GBP_BRANCH Commit the changes so far: $ debcommit -a -m'new upstream release 2.00' Don't forget to share your work when ready: $ dpt push =head1 Patches L does a fine job managing patches, especially if using the C<3.0 (quilt)> source format. See L for a guide. L can be used for treating the patches as a series of commits. See L =head1 Branches From time to time, there is a need to work in a branch for a stable update or a security fix. Things are simple: First create a branch from the tag that represents the version currently in the archive: $ git checkout -b squeeze debian/2.40-5 If the C branch already exists, check it out and merge the version currently in the archive: $ git checkout squeeze $ git merge debian/2.40-5 From this point on, work normally in the C branch, build, tag and push. =head1 Mass changes For changes across many repos. Do them and $ mr commit from within the top directory of the repositories. Since our global F<~/.mrconfig> redefines B to not push to the repositories, don't forget to push afterwards: $ mr push I since KGB notifies now on C<#debian-perl-changes>, it is not mandatory (and probably not desirable) to disable KGB notifications before mass change anymore. If you want to do it anyway, you can use the following workflow: =over 4 =item * Disable the KGB notifications: $ dpt salsa kgb --all --off =item * Push to the Git repositories: $ =item * Re-enable the KGB notifications: $ dpt salsa kgb --all --on =back =head1 Commit policy =over =item single change per commit This is true for any VCS, but it won't hurt saying it again: please include only one change in each commit. L's and C's ability to stage single lines (or hunks) is a huge help if you have done several unrelated changes in the sources. =item changelog maintenance Some prefer to update F with each commit, while others prefer to do that only at release time by using L. The current group policy states that whenever you stop working on a package, the changelog should be updated and pushed. That is, either include the changelog entry with each commit, or finish your work by updating the changelog, e.g. via L. =back =head1 Removing packages When there is the need to remove a package from the group you can either remove it completely (if added without ever being released) or move it to the attic sub-group. This can be only done by using salsa's web interface and needs C privileges. =head1 Renaming packages When there is the need to rename a package from the group the project should be renamed as well. This can only be done by using salsa's web interface. =head1 Tips & tricks =head2 How to have git-buildpackage not ask for a password so often ? One of the annoying things about B is that when you check out a package using the C protocol, it asks for your password pretty often when building, about 25 times. This tends to get annoying by the second time you have to type in your password. To avoid this, upload your public SSH key in the account area (L). To avoid typing even the public key passphrase you may want to run SSH agent (see L, included in the C package). =head2 How to save typing when using pristine-tar? L has a configuration file which can save some typing on each command. The C option is particularly handy. An example of configuration file: [DEFAULT] pristine-tar = True sign-tags = True This may be stored for example in B<~/.gbp.conf> (per user configuration), in B (per branch configuration) or in B<.git/gbp.conf> (per repository configuration). If using the C<3.0 (quilt)> source format, it may also be handy to add the .pc directory to the F<.gitignore> file. To do this globally, you may use the following: git config --global --add core.excludesfile ~/.gitignore echo '/.pc/' >> ~/.gitignore (If you have a Git repository in your home, you probably want to use something else than F<~/.gitignore> for the global excludes file). =head2 Prevent surprises in the upstream tarball Sometimes the upstream tarball contains files that change the behaviour of git or mess with the debian directory in unexpected ways. These can be excluded on import with the following settings in F<~/.gbp.conf>, or, for the benefit of others, in F: [import-orig] filter = [ '.gitignore', 'debian/*', '.git/*', '.git' ] [import-dsc] filter = [ '.gitignore', '.git/*', '.git' ] =head2 More goodies from pkg-perl-tools Take a look at L and the other scripts in the B package. =head1 Caveats Git is detached. This is very good, when you happen to work mainly offline or on the road. The problem is not to forget to publish your work at some point in time :) Various shell hooks that change the prompt may be of help. =head1 Authors =over =item * Damyan Ivanov =item * gregor herrmann =back =head1 License Copyright (c) 2010-2018 by the individual authors and contributors noted above. All rights reserved. This document is free software; you may redistribute it and/or modify it under the same terms as Perl itself Perl is distributed under your choice of the GNU General Public License version 1 or later or the Artistic License. On Debian systems, the complete text of the GNU General Public License version 1 can be found in `/usr/share/common-licenses/GPL-1' and the Artistic License in `/usr/share/common-licenses/Artistic'. =for comment vim:tw=79