Ubuntu Packaging Guide Specification

Audience: Experienced users who wish to make Ubuntu packages
Document Outline: See the Document Outline section below.
Target Presentation Formats: xml, html, pdf
License: GPL
Technologies and Techniques: DocBook xml and stored in the docteam's svn repo.
Release Target: Dapper
Links to Current Version: It's included in Dapper, a more current version can be viewed here.
How to Contribute: The best way to contribute is to send patches to the ubuntu-doc mailing list (ubuntu-doc@lists.ubuntu.com)
Primary Contacts: DocumentationTeam, JordanMantha
Contributors: CoreyBurger2, AlexandreVassalotti,

Summary

The Packaging Guide is the official guide for people wanting to build and maintain packages in Ubuntu. It provides an easy introduction to building source packages as well as knowledge needed to become an Ubuntu Universe maintainer (MOTU).

Brain Dump

The guide should reflect the different processes a packager can face. For example, the packager could, instead of building the package from scratch, import one from Debian. So, the guide should tell how to do so. It may make the guide a little bit redundant, but will help new packager a lot.
Integrate Common Mistakes throughout sections, as they come up.
Integrate Kubuntu packaging throughout unless we get a large amount of material.
Flowchart type explanation at the introduction that directs different types of readers (beginning, advanced, non-Ubuntu developers) to the right chapters.
Better coverage of updating/modifying existing packages.
Add content for piuparts?
Library packaging from http://www.netfort.gr.jp/~dancer/column/libpkg-guide/libpkg-guide.html
clarify that dchroot is not for building packages and also try to give a few examples of actually using a chroot.
talk more about --base-tgz in pbuilder, especially what the default is so you can find our .debs
explain gpg key stuff more (i.e. using -k and seting env. variables)
in dchroot do we need to get rid of sudo stuff? Infinity suggested using sudo dchroot -c <chroot>
info for backporting
how to get package info from LP? (might be better in developer's reference)
REVU part should mention that authentication is done via the revu-uploaders LP team
especially note that debian/rules needs to be chmod +x
A glossary?
An example of good packaging environment setup would be nice. (directories layout, version control, etc)

Resources

MOTU/Documentation also has a list of wiki and web resources for packaging. We should try to incorporate as much as we can and clean the wiki as well.

* http://xgen.iit.edu/cgi-bin/man/man2html?7+debhelper

Outline

About This Guide (Common Preface)
Introduction
1. Introductory paragraph
2. Set flow for different reader types
3. What is a package?
  - The Debian Package Format
  - Binary and Source Packages
  - What a package contains?
  - How packages get from the developers to your computer
Setting your workplace
- Tips about directory layout
- Editing helpers (for changelog, control, etc)
- Installing build dependencies
- (Maybe) Configuring pbuilder
Overview of Packaging Tools
1. Introduction
2. Standard tools
  - build-essential
  - devscripts
  - debhelper / dh_make
  - gnupg
3. Build helper systems
  - debhelper
  - dbs
  - cdbs
4. Package Builders
  - dpkg-buildpackage
  - debuild
  - pbuilder
5. Patch systems
  - Dpatch
  - Quilt
  - Simple-patch-sys
6. Error checking
  - lintian / linda
  - debdiff
7. Version control systems
  - bzr / builddeb
Examples Tasks
1. Modifying an existing package.
  - Getting the source code
  - New changelog entries
  - Building and testing
2. Creating a new package.
  - The package description files
    - "control and changelog"
  - Finding the dependencies
  - Writing the package build process
    - "the `rules' file"
  - Building and testing
3. Importing a package from Debian
  - Changing the maintainer
  - Update bug tracker location
  - Removing Debian-specific patches
4. Adding new patches.
  - Backporting fixes from newer releases
  - Ubuntu-specific patches
5. New upstream release.
  - Changing debian/rules
  - Newly added documentation.
  - Updating the changelog.
  - Closing existing bugs.
6. Packaging development code.
  - When to do that?
  - Creating a source tarball
Packaging for Ubuntu
1. Ubuntu Release Process
2. Relationship with Debian
3. Updating Packages
  - New upstream release
  - Updating the current package (uupdate and friends)
  - Fixing other people's packages
4. New Packages
  - Debian Free Software Guidelines
  - Ubuntu Components
5. Merges and Syncs
6. Uploading your package
  - Sponsorship
7. Quality Control
  - Package Review
  - Tracking Bugs
Appendix
1. Additional Resources
2. Chroot Environment
3. dh_make example files
4. List of debhelper scripts
GNU General Public Licence

CategorySpec