docs/project/debian_packaging_guide.pod

   1 # Copyright (C) 2007, Parrot Foundation.
   2 # $Id$
   3
   4 =head1 Debian Packaging Guide
   5
   6 This is a quick set of instructions for packaging Parrot for Debian. See the
   7 Debian New Maintainer's Guide (http://www.debian.org/doc/maint-guide) for more
   8 information. The Ubuntu Packaging Guide is also a good resource
   9 (http://doc.ubuntu.com/ubuntu/packagingguide/C/).
  10
  11 This guide assumes that you're running in a chroot environment set up as in:
  12 L<https://trac.parrot.org/parrot/wiki/ChrootSetup>. For other configurations,
  13 see that page for a list of Debian packages you will need to install before
  14 building the Parrot packages.
  15
  16 To package Parrot for Debian:
  17
  18 =over 4
  19
  20 =item 0.
  21
  22 Download the latest tarball.
  23
  24 =item 1.
  25
  26 Compile it and run the tests, just to be sure the tarball is sound (especially
  27 useful if you're running in a chroot environment different than your usual dev
  28 environment).
  29
  30 =item 2.
  31
  32 Create a new directory. (The name is irrelevant, but we'll use ~/deb/parrot for
  33 the sake of illustration.)
  34
  35 Create a fresh extract of the tarball in the ~/deb/parrot directory. The
  36 directory should be named "parrot-<version>" (it will be by default).
  37
  38 Copy the debian/ directory from the Parrot source tree into the fresh tarball
  39 extract.
  40
  41   cp -r <path/to/parrot/svn>/ports/debian ~/deb/parrot/parrot-<version>/.
  42
  43 Copy the original tarball into ~/deb/parrot, naming it
  44 "parrot_<version>.orig.tar.gz" (note the "_" in place of dash).
  45
  46 =item 3.
  47
  48 Update the debian/changelog file in ~/deb/parrot/parrot-<version>/. The format
  49 of the changelog file is strict (automatically parsed). The first line of the
  50 log entry gives the package version and categorization. For a new version
  51 upload, the version number is the Parrot version number followed by -1. For
  52 example:
  53
  54   parrot (0.5.1-1) unstable; urgency=low
  55
  56 The next few lines are the changelog record entries. These record changes in
  57 the Debian packaging of Parrot, not changes in Parrot itself. New package
  58 versions should include the line:
  59
  60   * New upstream release.
  61
  62 Please note any closed bugs related to the Parrot packages with an entry that
  63 includes the text "(Closes: #<bugnum>)".
  64
  65 The final line gives the maintainer's name, email address, and the date. The
  66 date must be in RFC822 format, and can be generated by running C<date -R>.
  67 (Note that two spaces are required between the email and the date.)
  68
  69    -- Your Name <you@example.org>  Sun, 30 Dec 2007 17:21:45 +0000
  70
  71 =item 4.
  72
  73 Update the debian/control.in file in ~/deb/parrot/parrot-<version>/. Make sure
  74 you are listed in "Uploaders". The "Maintainer" will always be "Debian
  75 Parrot Maintainers <pkg-parrot-devel@lists.alioth.debian.org>".
  76
  77 =item 5.
  78
  79 Update the debian/copyright file in ~/deb/parrot/parrot-<version>/. Check for
  80 any removed files that no longer need copyright notices. Update the years in
  81 the Parrot Foundation copyright line if needed.
  82
  83 =item 6.
  84
  85 Make sure you have C<quilt> installed. Run:
  86
  87   $ aptitude install quilt
  88
  89 =item 7.
  90
  91 Regenerate the debian/control file. From the
  92 ~/deb/parrot/parrot-<version>/ directory, run:
  93
  94   $ debian/rules debian-control-stamp
  95
  96 =item 8.
  97
  98 Install all dependencies:
  99
 100   $ sudo /usr/lib/pbuilder/pbuilder-satisfydepends
 101
 102 =item 9.
 103
 104 Build the packages. From ~/deb/parrot/parrot_<version>/, run:
 105
 106   $ export DEBSIGN_KEYID="<gpg key id>"
 107   $ debuild
 108
 109 =item 10.
 110
 111 Check the package for errors. From ~/deb/parrot, run:
 112
 113   $ lintian -i parrot_<version>.changes
 114
 115 =item 11.
 116
 117 Commit all changes made to the files in the debian/ directory to the Parrot
 118 repository.
 119
 120 =item 12.
 121
 122 Upload the packages to http://alioth.debian.org. (If you don't have admin
 123 privileges, ask someone who does.) From any of the project pages, click on the
 124 "Admin" tab, then the "FRS Admin" link on the bottom of the page, then the link
 125 to "quick-release a file".
 126
 127 Select the appropriate "Package ID" for the file (the same as the filename
 128 without the version). For the "Release Name" use the current version number
 129 (e.g.  0.6.1). For the "Release Date" use the date and time you listed in the
 130 debian changelog file (the date and time the debian package was created, not
 131 Parrot's release date for that version). For the "Release Notes" use the
 132 standard release text (the email/website/press announcement) without the change
 133 list.  For the "Change Log" use the change list from the standard release text.
 134 Also check "Preserve my pre-formatted text".
 135
 136 =back
 137
 138 =head1 SEE ALSO
 139
 140 F<README>, F<RESPONSIBLE_PARTIES>.
 141
 142 =head1 Appendix 1
 143
 144 Parrot Debian Release Managers
 145
 146  - Allison Randal
 147  - Nuno Carvalho
 148  - Patrick Michaud
 149
 150 Parrot Debian Sponsors
 151
 152  - Colin Watson
 153  - Jeff Bailey
 154  - Benjamin Mako Hill
 155
 156 =head1 Appendix 2
 157
 158 Set up instructions for new Debian Parrot release managers.
 159
 160 =over 4
 161
 162 =item 0.
 163
 164 Create an account on http://alioth.debian.org and request to join the group
 165 pkg-parrot.
 166
 167 =item 1.
 168
 169 If you will be uploading through a sponsor, create an account on
 170 http://mentors.debian.net.
 171
 172 =item 2.
 173
 174 Set up a chroot environment for building packages. See
 175 <http://trac.parrot.org/parrot/wiki/ChrootSetup>.
 176
 177 =back
 178
 179 =cut