# Copyright (C) 2007, Parrot Foundation.
# $Id: debian_packaging_guide.pod 46285 2010-05-04 15:54:14Z coke $

=head1 Debian Packaging Guide

This is a quick set of instructions for packaging Parrot for Debian. See the
Debian New Maintainer's Guide (http://www.debian.org/doc/maint-guide) for more
information. The Ubuntu Packaging Guide is also a good resource
(http://doc.ubuntu.com/ubuntu/packagingguide/C/).

This guide assumes that you're running in a chroot environment set up as in:
L<https://trac.parrot.org/parrot/wiki/ChrootSetup>. For other configurations,
see that page for a list of Debian packages you will need to install before
building the Parrot packages.

To package Parrot for Debian:

=over 4

=item 0.

Download the latest tarball.

=item 1.

Compile it and run the tests, just to be sure the tarball is sound (especially
useful if you're running in a chroot environment different than your usual dev
environment).

=item 2.

Create a new directory. (The name is irrelevant, but we'll use ~/deb/parrot for
the sake of illustration.)

Create a fresh extract of the tarball in the ~/deb/parrot directory. The
directory should be named "parrot-<version>" (it will be by default).

Copy the debian/ directory from the Parrot source tree into the fresh tarball
extract.

  cp -r <path/to/parrot/svn>/ports/debian ~/deb/parrot/parrot-<version>/.

Copy the original tarball into ~/deb/parrot, naming it
"parrot_<version>.orig.tar.gz" (note the "_" in place of dash).

=item 3.

Update the debian/changelog file in ~/deb/parrot/parrot-<version>/. The format
of the changelog file is strict (automatically parsed). The first line of the
log entry gives the package version and categorization. For a new version
upload, the version number is the Parrot version number followed by -1. For
example:

  parrot (0.5.1-1) unstable; urgency=low

The next few lines are the changelog record entries. These record changes in
the Debian packaging of Parrot, not changes in Parrot itself. New package
versions should include the line:

  * New upstream release.

Please note any closed bugs related to the Parrot packages with an entry that
includes the text "(Closes: #<bugnum>)".

The final line gives the maintainer's name, email address, and the date. The
date must be in RFC822 format, and can be generated by running C<date -R>.
(Note that two spaces are required between the email and the date.)

   -- Your Name <you@example.org>  Sun, 30 Dec 2007 17:21:45 +0000

=item 4.

Update the debian/control.in file in ~/deb/parrot/parrot-<version>/. Make sure
you are listed in "Uploaders". The "Maintainer" will always be "Debian
Parrot Maintainers <pkg-parrot-devel@lists.alioth.debian.org>".

=item 5.

Update the debian/copyright file in ~/deb/parrot/parrot-<version>/. Check for
any removed files that no longer need copyright notices. Update the years in
the Parrot Foundation copyright line if needed.

=item 6.

Make sure you have C<quilt> installed. Run:

  $ aptitude install quilt

=item 7.

Regenerate the debian/control file. From the
~/deb/parrot/parrot-<version>/ directory, run:

  $ debian/rules debian-control-stamp

=item 8.

Install all dependencies:

  $ sudo /usr/lib/pbuilder/pbuilder-satisfydepends

=item 9.

Build the packages. From ~/deb/parrot/parrot_<version>/, run:

  $ export DEBSIGN_KEYID="<gpg key id>"
  $ debuild

=item 10.

Check the package for errors. From ~/deb/parrot, run:

  $ lintian -i parrot_<version>.changes

=item 11.

Commit all changes made to the files in the debian/ directory to the Parrot
repository.

=item 12.

Upload the packages to http://alioth.debian.org. (If you don't have admin
privileges, ask someone who does.) From any of the project pages, click on the
"Admin" tab, then the "FRS Admin" link on the bottom of the page, then the link
to "quick-release a file".

Select the appropriate "Package ID" for the file (the same as the filename
without the version). For the "Release Name" use the current version number
(e.g.  0.6.1). For the "Release Date" use the date and time you listed in the
debian changelog file (the date and time the debian package was created, not
Parrot's release date for that version). For the "Release Notes" use the
standard release text (the email/website/press announcement) without the change
list.  For the "Change Log" use the change list from the standard release text.
Also check "Preserve my pre-formatted text".

=back

=head1 SEE ALSO

F<README>, F<RESPONSIBLE_PARTIES>.

=head1 Appendix 1

Parrot Debian Release Managers

 - Allison Randal
 - Nuno Carvalho
 - Patrick Michaud

Parrot Debian Sponsors

 - Colin Watson
 - Jeff Bailey
 - Benjamin Mako Hill

=head1 Appendix 2

Set up instructions for new Debian Parrot release managers.

=over 4

=item 0.

Create an account on http://alioth.debian.org and request to join the group
pkg-parrot.

=item 1.

If you will be uploading through a sponsor, create an account on
http://mentors.debian.net.

=item 2.

Set up a chroot environment for building packages. See
<http://trac.parrot.org/parrot/wiki/ChrootSetup>.

=back

=cut
