# Copyright (C) 2007-2009, Parrot Foundation.
# $Id: ubuntu_packaging_guide.pod 40439 2009-08-07 01:58:49Z allison $

=head1 Ubuntu Packaging Guide

This is a quick set of instructions for packaging Parrot for Ubuntu. See the he
Ubuntu Packaging Guide (https://wiki.ubuntu.com/PackagingGuide) and the guide
to the Person Package Archive (PPA) (https://help.launchpad.net/Packaging/PPA)
for more details.

This guide assumes that you're running in a chroot environment set up as in:
L<https://trac.parrot.org/parrot/wiki/ChrootSetup>, and also assumes that
you've already built the corresponding Debian package for the release as
documented in L<docs/project/debian_packaging_guide.pod>.

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 F<~/udeb/parrot> for
the sake of illustration.)

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

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

=item 3.

Integrate any new change entries from F<ports/debian/changelog> into
F<ports/ubuntu/changelog>, preserving chronological order.

Copy the F<ports/debian/> directory from the Parrot source tree into the fresh
tarball extract.

  cp -r <path/to/parrot/svn>/ports/debian ~/udeb/parrot/parrot-[version]/.


Then copy the unique Ubuntu files (F<changelog> and F<control.in>) from
F<ports/ubuntu/> into the new F<debian/> directory.

  cp <path/to/parrot/svn>/ports/ubuntu/* ~/udeb/parrot/parrot-[version]/debian/.

=item 4.

Add a new entry to the F<changelog> file in
F<~/udeb/parrot/parrot-[version]/debian/> for the Ubuntu package. Copy
the first line from the Debian changelog. Add C<ubuntu#> after the
Debian version to indicate the Ubuntu revision of the package, and for
PPA uploads also add C<~ppa#>. Instead of the Debian branch ('unstable')
use the target Ubuntu distribution ('intrepid').

  parrot (0.5.1-1ubuntu1) intrepid; urgency=low

The changelog entry for the Ubuntu release is generally:

  * Synchronize with Debian unstable.

Add any custom changes for Ubuntu packaging (rare). 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 5.

Install all dependencies:

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

=item 6.

Build the source packages. From F<~/udeb/parrot/parrot_[version]/>, run:

  $ debuild -S -sa

=item 7.

Update Parrot's PPA with the new release (configured in ChrootSetup).
From F<~/udeb/parrot/> run:

  $ dput parrot-ppa parrot_[version]_source.changes

=item 8.

Commit the Ubuntu F<changelog> file to the F<ports/ubuntu/> directory in the
repository. (At the moment, we're keeping the Debian packages as the primary.)

=back

=cut