Debian Developer’s Reference Developer’s Reference Team <[email protected]> Andreas Barth Adam Di Carlo Raphaël Hertzog Christian Schwarz Ian Jackson ver. 3.3.9, 04 August, 2007 Copyright Notice copyright © 2004—2007 Andreas Barth copyright © 1998—2003 Adam Di Carlo copyright © 2002—2003 Raphaël Hertzog copyright © 1997, 1998 Christian Schwarz This manual is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. This is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details. A copy of the GNU General Public License is available as /usr/share/common-licenses /GPL in the Debian GNU/Linux distribution or on the World Wide Web at the GNU web site (http://www.gnu.org/copyleft/gpl.html). You can also obtain it by writing to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. i Contents 1 Scope of This Document 1 2 Applying to Become a Maintainer 3 2.1 Getting started ....................................... 3 2.2 Debian mentors and sponsors .............................. 4 2.3 Registering as a Debian developer ........................... 4 3 Debian Developer’s Duties 7 3.1 Maintaining your Debian information ......................... 7 3.2 Maintaining your public key ............................... 7 3.3 Voting ............................................ 8 3.4 Going on vacation gracefully .............................. 8 3.5 Coordination with upstream developers ........................ 9 3.6 Managing release-critical bugs ............................. 9 3.7 Retiring ........................................... 9 4 Resources for Debian Developers 11 4.1 Mailing lists ........................................ 11 4.1.1 Basic rules for use ................................. 11 4.1.2 Core development mailing lists ......................... 12 4.1.3 Special lists .................................... 12 4.1.4 Requesting new development-related lists .................. 12 4.2 IRC channels ........................................ 13 4.3 Documentation ...................................... 13 4.4 Debian machines ..................................... 14 CONTENTS ii 4.4.1 The bugs server .................................. 14 4.4.2 The ftp-master server .............................. 15 4.4.3 The www-master server ............................. 15 4.4.4 The people web server .............................. 15 4.4.5 The VCS servers ................................. 15 4.4.6 chroots to different distributions ........................ 16 4.5 The Developers Database ................................ 16 4.6 The Debian archive .................................... 17 4.6.1 Sections ...................................... 18 4.6.2 Architectures ................................... 19 4.6.3 Packages ...................................... 20 4.6.4 Distributions ................................... 20 4.6.5 Release code names ............................... 22 4.7 Debian mirrors ...................................... 23 4.8 The Incoming system ................................... 23 4.9 Package information ................................... 24 4.9.1 On the web .................................... 24 4.9.2 The madison utility ............................... 24 4.10 The Package Tracking System .............................. 25 4.10.1 The PTS email interface ............................. 26 4.10.2 Filtering PTS mails ................................ 27 4.10.3 Forwarding VCS commits in the PTS ..................... 27 4.10.4 The PTS web interface .............................. 27 4.11 Developer’s packages overview ............................. 29 4.12 Debian’s GForge installation: Alioth .......................... 29 4.13 Goodies for Developers ................................. 30 4.13.1 LWN Subscriptions ................................ 30 5 Managing Packages 31 5.1 New packages ....................................... 31 5.2 Recording changes in the package ........................... 32 CONTENTS iii 5.3 Testing the package .................................... 32 5.4 Layout of the source package .............................. 33 5.5 Picking a distribution ................................... 34 5.5.1 Special case: uploads to the stable distribution ................ 34 5.5.2 Special case: uploads to testing/testing-proposed-updates ........... 35 5.6 Uploading a package ................................... 35 5.6.1 Uploading to ftp-master ........................... 35 5.6.2 Delayed uploads ................................. 35 5.6.3 Security uploads ................................. 36 5.6.4 Other upload queues ............................... 36 5.6.5 Notification that a new package has been installed .............. 36 5.7 Specifying the package section, subsection and priority ............... 37 5.8 Handling bugs ....................................... 37 5.8.1 Monitoring bugs ................................. 38 5.8.2 Responding to bugs ............................... 38 5.8.3 Bug housekeeping ................................ 39 5.8.4 When bugs are closed by new uploads .................... 40 5.8.5 Handling security-related bugs ......................... 41 5.9 Moving, removing, renaming, adopting, and orphaning packages ......... 45 5.9.1 Moving packages ................................. 45 5.9.2 Removing packages ............................... 46 5.9.3 Replacing or renaming packages ........................ 47 5.9.4 Orphaning a package .............................. 47 5.9.5 Adopting a package ............................... 48 5.10 Porting and being ported ................................. 48 5.10.1 Being kind to porters ............................... 48 5.10.2 Guidelines for porter uploads .......................... 50 5.10.3 Porting infrastructure and automation ..................... 51 5.10.4 When your package is not portable ....................... 52 5.11 Non-Maintainer Uploads (NMUs) ........................... 53 5.11.1 How to do a NMU ................................ 54 CONTENTS iv 5.11.2 NMU version numbering ............................ 55 5.11.3 Source NMUs must have a new changelog entry ............... 55 5.11.4 Source NMUs and the Bug Tracking System ................. 56 5.11.5 Building source NMUs .............................. 56 5.11.6 Acknowledging an NMU ............................ 56 5.11.7 NMU vs QA uploads ............................... 57 5.11.8 Who can do an NMU ............................... 57 5.11.9 Terminology .................................... 57 5.12 Collaborative maintenance ................................ 58 5.13 The testing distribution .................................. 59 5.13.1 Basics ........................................ 59 5.13.2 Updates from unstable .............................. 59 5.13.3 Direct updates to testing ............................. 62 5.13.4 Frequently asked questions ........................... 63 6 Best Packaging Practices 65 6.1 Best practices for debian/rules ........................... 65 6.1.1 Helper scripts ................................... 65 6.1.2 Separating your patches into multiple files .................. 66 6.1.3 Multiple binary packages ............................ 67 6.2 Best practices for debian/control .......................... 67 6.2.1 General guidelines for package descriptions ................. 67 6.2.2 The package synopsis, or short description .................. 68 6.2.3 The long description ............................... 69 6.2.4 Upstream home page ............................... 69 6.2.5 Version Control System location ........................ 70 6.3 Best practices for debian/changelog ........................ 71 6.3.1 Writing useful changelog entries ........................ 71 6.3.2 Common misconceptions about changelog entries .............. 71 6.3.3 Common errors in changelog entries ...................... 72 6.3.4 Supplementing changelogs with NEWS.Debian files ............. 73 CONTENTS v 6.4 Best practices for maintainer scripts .......................... 74 6.5 Configuration management with debconf ...................... 75 6.5.1 Do not abuse debconf .............................. 75 6.5.2 General recommendations for authors and translators ............ 75 6.5.3 Templates fields definition ............................ 78 6.5.4 Templates fields specific style guide ...................... 79 6.6 Internationalization .................................... 82 6.6.1 Handling debconf translations ......................... 82 6.6.2 Internationalized documentation ........................ 82 6.7 Common packaging situations ............................. 83 6.7.1 Packages using autoconf/automake .................... 83 6.7.2 Libraries ...................................... 83 6.7.3 Documentation .................................. 83 6.7.4 Specific types of packages ............................ 83 6.7.5 Architecture-independent data ......................... 84 6.7.6 Needing a certain locale during build ..................... 84 6.7.7 Make transition packages deborphan compliant ............... 85 6.7.8 Best practices for orig.tar.gz files ..................... 85 6.7.9 Best practices for debug packages ....................... 88 7 Beyond Packaging 89 7.1 Bug reporting ......................................