r65982 - /website/git.pod

Sun Dec 19 07:17:48 UTC 2010

Author: dmn
Date: Sun Dec 19 07:15:51 2010
New Revision: 65982

URL: http://svn.debian.org/wsvn/?sc=1&rev=65982
Log:
add a short guide for managing pkg-perl packages in Git

Added:
    website/git.pod

Added: website/git.pod
URL: http://svn.debian.org/wsvn/website/git.pod?rev=65982&op=file
==============================================================================

--- website/git.pod (added)
+++ website/git.pod Sun Dec 19 07:15:51 2010
@@ -1,0 +1,167 @@
+
+=head1 Debian Perl Group Git Guide (BETA)
+
+This guide describes the procedures that the Debian Perl Group contributors use
+to maintain packages in the Git repositories on git.debian.org.
+
+It will describe how to upload an initial package, how to update the packages,
+how to build them and how to upgrade them.
+
+The guide is a work in proggress. Different people tent 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
+<debian-perl at lists.debian.org>.
+
+=head1 1. The Tools
+
+Most of the tools you will be using will come from either the
+B<git-buildpackage> or the B<git> packages.
+
+=head1 2. Packaging walkthrough
+
+=head2 * starting the package
+
+B<git-import-dsc> is used to introduce the source of a package into the Git
+repository. It operates on the C<.dsc> file and the associated source files. It
+checks in the package and upstream code in the Git repository.
+
+Example of starting a new package from scratch:
+
+    $ dh-make-perl [option...] --cpan Foo
+    ...
+    $ mkdir libfoo-perl
+    $ cd libfoo-perl
+    $ git init
+    $ git-import-dsc --pristine-tar ../libfoo-perl_1.23-1.dsc
+
+Note that L<dh-make-perl(1)> has many options to make your life easier.
+
+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.
+
+=head2 * cloning existing package repository
+
+This can be done with plain L<git-clone(1)>, but using gbp-clone will setup
+tracking branches for upstream sources and pristine-tar data:
+
+    $ gbp-clone ssh://git.debian.org/git/pkg-perl/packages/libfoo-perl.git
+
+=head2 * repossitory layout
+
+Upstream sources are kept (in plain, uncompressed form) in the C<upstream>
+branch. The original source tarballs are kept with the help of the
+L<pristine-tar(1)> tool in the C<pristine-tar> branch. The merge of the
+upstream sources and Debian-related changes is in the C<master> branch, which
+is the usual place to work in.
+
+From this point on, work on the package normally. Some prefer to update
+debian/changelog with each commit, others leave this to the L<git-dch(1)> tool
+at package release time.
+
+=head2 * pushing to git.debian.org
+
+Before pushing to git.debian.org for the first time, an empty repository needs
+to be created there. To do this, use the B<setup-repository> script available
+in the C</git/pkg-perl> directory. Run it similarly to:
+
+    $ ssh git.debian.org
+    $ cd /git/pkg-perl/packages
+    $ ../setup-repository libfoo-perl 'Packaging of FOO in Debian'
+
+This will create an empty, bare, shared Git repository and setup some hooks.
+
+Each package is kept in its own Git repository. We don't use git-submodules.
+L<mr(1)> may be of help if you need to track several packages.
+
+TODO: give example mr setup
+
+Now, on your local machine add the alioth repository as a remote:
+
+    $ git remote add origin ssh://git.debian.org/git/pkg-perl/packages/libfoo-perl.git
+
+Then push to it:
+
+    $ git push --all --set-upstream
+    $ git push --tags
+
+The C<--set-upstream> option helps future use ot C<git pull>.
+
+=head2 * building the package
+
+Use your favourite way of building the Debian package. If the source tarball is
+not in ../, check it out from the pristine-tar info:
+
+    $ pristine-tar checkout ../libfoo-bar-perl_1.23_orig.tar.gz
+
+This requires that you have the C<pristine-tar> current (e.g. via C<git fetch>
+or L<gbp-pull(1)>).
+
+After uploading, tag the release. The easiest way is to use L<debcommit(1)>
+
+    $ debcommit -a -r
+
+Push the result afterwards:
+
+    $ git push
+    $ git push --tags
+
+=head2 * upgrading to a new upstream release
+
+First make sure that the local repository is up to date, for example using
+L<gbp-pull(1)>. Then import the new upstream release:
+
+ $ git-import-orig --pritine-tar ../libfoo-bar-perl_2.00_orig.tar.gz
+
+This will import the new sources in the C<upstream> branch, update tarball info
+in the C<pristine-tar> branch, tag the upstream release and finally merge that
+tag in the C<master> branch. It would also update debian/changelog.
+
+ $ debcommit -a -m'new upsream release 2.00'
+
+Don't forget to share your work when ready:
+
+ $ git push --all
+ $ git push --tags
+
+=head2 * patches
+
+L<quilt(1)> does a fine job managing patches, especially if using the C<(3.0)
+quilt> source format. See L<http://pkg-perl.alioth.debian.org/howto/quilt.html>
+for a guide. L<gbp-pq(1)> can be used for treating the patches as a series of
+commits. See
+L<https://honk.sigxcpu.org/piki/development/debian_packages_in_git/>
+
+=head1 TIPS & TRICKS
+
+L<git-buildpackage(1)> has a configuration file whch can save some typing on
+each command. The C<pristine-tar> option is particularly handy.
+
+=head1 CAVEATS
+
+Git is detached. This is very good, when you prefer to work mainly offline or
+on the road. The problem is not to forget to publish your work at some point in
+time :)
+
+=head1 Authors
+
+=over
+
+=item * Damyan Ivanov
+
+=back
+
+=head1 License
+
+Copyright (c) 2010 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


