1 # SOME DESCRIPTIVE TITLE
2 # Copyright (C) YEAR Free Software Foundation, Inc.
3 # This file is distributed under the same license as the PACKAGE package.
4 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
9 "Project-Id-Version: PACKAGE VERSION\n"
10 "POT-Creation-Date: 2011-04-22 10:29-0400\n"
11 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
12 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
13 "Language-Team: LANGUAGE <LL@li.org>\n"
16 "Content-Type: text/plain; charset=UTF-8\n"
17 "Content-Transfer-Encoding: 8bit\n"
19 #. type: Content of: <chapter><title>
20 #: beyond-pkging.dbk:7
21 msgid "Beyond Packaging"
24 #. type: Content of: <chapter><para>
25 #: beyond-pkging.dbk:9
27 "Debian is about a lot more than just packaging software and maintaining "
28 "those packages. This chapter contains information about ways, often really "
29 "critical ways, to contribute to Debian beyond simply creating and "
30 "maintaining packages."
33 #. type: Content of: <chapter><para>
34 #: beyond-pkging.dbk:14
36 "As a volunteer organization, Debian relies on the discretion of its members "
37 "in choosing what they want to work on and in choosing the most critical "
38 "thing to spend their time on."
41 #. type: Content of: <chapter><section><title>
42 #: beyond-pkging.dbk:19
46 #. type: Content of: <chapter><section><para>
47 #: beyond-pkging.dbk:21
49 "We encourage you to file bugs as you find them in Debian packages. In fact, "
50 "Debian developers are often the first line testers. Finding and reporting "
51 "bugs in other developers' packages improves the quality of Debian."
54 #. type: Content of: <chapter><section><para>
55 #: beyond-pkging.dbk:26
57 "Read the <ulink url=\"&url-bts-report;\">instructions for reporting bugs</"
58 "ulink> in the Debian <ulink url=\"&url-bts;\">bug tracking system</ulink>."
61 #. type: Content of: <chapter><section><para>
62 #: beyond-pkging.dbk:31
64 "Try to submit the bug from a normal user account at which you are likely to "
65 "receive mail, so that people can reach you if they need further information "
66 "about the bug. Do not submit bugs as root."
69 #. type: Content of: <chapter><section><para>
70 #: beyond-pkging.dbk:36
72 "You can use a tool like <citerefentry> <refentrytitle>reportbug</"
73 "refentrytitle> <manvolnum>1</manvolnum> </citerefentry> to submit bugs. It "
74 "can automate and generally ease the process."
77 #. type: Content of: <chapter><section><para>
78 #: beyond-pkging.dbk:41
80 "Make sure the bug is not already filed against a package. Each package has "
81 "a bug list easily reachable at <literal>http://&bugs-host;/"
82 "<replaceable>packagename</replaceable></literal>. Utilities like "
83 "<citerefentry> <refentrytitle>querybts</refentrytitle> <manvolnum>1</"
84 "manvolnum> </citerefentry> can also provide you with this information (and "
85 "<command>reportbug</command> will usually invoke <command>querybts</command> "
86 "before sending, too)."
89 #. type: Content of: <chapter><section><para>
90 #: beyond-pkging.dbk:50
92 "Try to direct your bugs to the proper location. When for example your bug "
93 "is about a package which overwrites files from another package, check the "
94 "bug lists for <emphasis>both</emphasis> of those packages in order to avoid "
95 "filing duplicate bug reports."
98 #. type: Content of: <chapter><section><para>
99 #: beyond-pkging.dbk:56
101 "For extra credit, you can go through other packages, merging bugs which are "
102 "reported more than once, or tagging bugs `fixed' when they have already been "
103 "fixed. Note that when you are neither the bug submitter nor the package "
104 "maintainer, you should not actually close the bug (unless you secure "
105 "permission from the maintainer)."
108 #. type: Content of: <chapter><section><para>
109 #: beyond-pkging.dbk:63
111 "From time to time you may want to check what has been going on with the bug "
112 "reports that you submitted. Take this opportunity to close those that you "
113 "can't reproduce anymore. To find out all the bugs you submitted, you just "
114 "have to visit <literal>http://&bugs-host;/from:<replaceable>your-email-addr</"
115 "replaceable></literal>."
118 #. type: Content of: <chapter><section><section><title>
119 #: beyond-pkging.dbk:70
120 msgid "Reporting lots of bugs at once (mass bug filing)"
123 #. type: Content of: <chapter><section><section><para>
124 #: beyond-pkging.dbk:72
126 "Reporting a great number of bugs for the same problem on a great number of "
127 "different packages — i.e., more than 10 — is a deprecated practice. Take "
128 "all possible steps to avoid submitting bulk bugs at all. For instance, if "
129 "checking for the problem can be automated, add a new check to <systemitem "
130 "role=\"package\">lintian</systemitem> so that an error or warning is emitted."
133 #. type: Content of: <chapter><section><section><para>
134 #: beyond-pkging.dbk:79
136 "If you report more than 10 bugs on the same topic at once, it is recommended "
137 "that you send a message to &email-debian-devel; describing your intention "
138 "before submitting the report, and mentioning the fact in the subject of your "
139 "mail. This will allow other developers to verify that the bug is a real "
140 "problem. In addition, it will help prevent a situation in which several "
141 "maintainers start filing the same bug report simultaneously."
144 #. type: Content of: <chapter><section><section><para>
145 #: beyond-pkging.dbk:87
147 "Please use the programs <command>dd-list</command> and if appropriate "
148 "<command>whodepends</command> (from the package <systemitem role=\"package"
149 "\">devscripts</systemitem>) to generate a list of all affected packages, and "
150 "include the output in your mail to &email-debian-devel;."
153 #. type: Content of: <chapter><section><section><para>
154 #: beyond-pkging.dbk:93
156 "Note that when sending lots of bugs on the same subject, you should send the "
157 "bug report to <email>maintonly@&bugs-host;</email> so that the bug report is "
158 "not forwarded to the bug distribution mailing list."
161 #. type: Content of: <chapter><section><section><section><title>
162 #: beyond-pkging.dbk:98
166 #. type: Content of: <chapter><section><section><section><para>
167 #: beyond-pkging.dbk:100
169 "You may wish to use BTS usertags when submitting bugs across a number of "
170 "packages. Usertags are similar to normal tags such as 'patch' and 'wishlist' "
171 "but differ in that they are user-defined and occupy a namespace that is "
172 "unique to a particular user. This allows multiple sets of developers to "
173 "'usertag' the same bug in different ways without conflicting."
176 #. type: Content of: <chapter><section><section><section><para>
177 #: beyond-pkging.dbk:107
179 "To add usertags when filing bugs, specify the <literal>User</literal> and "
180 "<literal>Usertags</literal> pseudo-headers:"
183 #. type: Content of: <chapter><section><section><section><screen>
184 #: beyond-pkging.dbk:111
187 "To: submit@bugs.debian.org\n"
188 "Subject: <replaceable>title-of-bug</replaceable>\n"
190 "Package: <replaceable>pkgname</replaceable>\n"
191 "<replaceable>[ ... ]</replaceable>\n"
192 "User: <replaceable>email-addr</replaceable>\n"
193 "Usertags: <replaceable>tag-name [ tag-name ... ]</replaceable>\n"
195 "<replaceable>description-of-bug ...</replaceable>\n"
198 #. type: Content of: <chapter><section><section><section><para>
199 #: beyond-pkging.dbk:122
201 "Note that tags are seperated by spaces and cannot contain underscores. If "
202 "you are filing bugs for a particular group or team it is recommended that "
203 "you set the <literal>User</literal> to an appropriate mailing list after "
204 "describing your intention there."
207 #. type: Content of: <chapter><section><section><section><para>
208 #: beyond-pkging.dbk:128
210 "To view bugs tagged with a specific usertag, visit <literal>http://&bugs-"
211 "host;/cgi-bin/pkgreport.cgi?users=<replaceable>email-addr</replaceable>&"
212 "tag=<replaceable>tag-name</replaceable></literal>."
215 #. type: Content of: <chapter><section><title>
216 #: beyond-pkging.dbk:137
217 msgid "Quality Assurance effort"
220 #. type: Content of: <chapter><section><section><title>
221 #: beyond-pkging.dbk:139
225 #. type: Content of: <chapter><section><section><para>
226 #: beyond-pkging.dbk:141
228 "Even though there is a dedicated group of people for Quality Assurance, QA "
229 "duties are not reserved solely for them. You can participate in this effort "
230 "by keeping your packages as bug-free as possible, and as lintian-clean (see "
231 "<xref linkend=\"lintian\"/>) as possible. If you do not find that possible, "
232 "then you should consider orphaning some of your packages (see <xref linkend="
233 "\"orphaning\"/>). Alternatively, you may ask the help of other people in "
234 "order to catch up with the backlog of bugs that you have (you can ask for "
235 "help on &email-debian-qa; or &email-debian-devel;). At the same time, you "
236 "can look for co-maintainers (see <xref linkend=\"collaborative-maint\"/>)."
239 #. type: Content of: <chapter><section><section><title>
240 #: beyond-pkging.dbk:155
241 msgid "Bug squashing parties"
244 #. type: Content of: <chapter><section><section><para>
245 #: beyond-pkging.dbk:157
247 "From time to time the QA group organizes bug squashing parties to get rid of "
248 "as many problems as possible. They are announced on &email-debian-devel-"
249 "announce; and the announcement explains which area will be the focus of the "
250 "party: usually they focus on release critical bugs but it may happen that "
251 "they decide to help finish a major upgrade (like a new <command>perl</"
252 "command> version which requires recompilation of all the binary modules)."
255 #. type: Content of: <chapter><section><section><para>
256 #: beyond-pkging.dbk:166
258 "The rules for non-maintainer uploads differ during the parties because the "
259 "announcement of the party is considered prior notice for NMU. If you have "
260 "packages that may be affected by the party (because they have release "
261 "critical bugs for example), you should send an update to each of the "
262 "corresponding bug to explain their current status and what you expect from "
263 "the party. If you don't want an NMU, or if you're only interested in a "
264 "patch, or if you will deal yourself with the bug, please explain that in the "
268 #. type: Content of: <chapter><section><section><para>
269 #: beyond-pkging.dbk:175
271 "People participating in the party have special rules for NMU, they can NMU "
272 "without prior notice if they upload their NMU to DELAYED/3-day at least. "
273 "All other NMU rules apply as usually; they should send the patch of the NMU "
274 "to the BTS (to one of the open bugs fixed by the NMU, or to a new bug, "
275 "tagged fixed). They should also respect any particular wishes of the "
279 #. type: Content of: <chapter><section><section><para>
280 #: beyond-pkging.dbk:182
282 "If you don't feel confident about doing an NMU, just send a patch to the "
283 "BTS. It's far better than a broken NMU."
286 #. type: Content of: <chapter><section><title>
287 #: beyond-pkging.dbk:190
288 msgid "Contacting other maintainers"
291 #. type: Content of: <chapter><section><para>
292 #: beyond-pkging.dbk:192
294 "During your lifetime within Debian, you will have to contact other "
295 "maintainers for various reasons. You may want to discuss a new way of "
296 "cooperating between a set of related packages, or you may simply remind "
297 "someone that a new upstream version is available and that you need it."
300 #. type: Content of: <chapter><section><para>
301 #: beyond-pkging.dbk:198
303 "Looking up the email address of the maintainer for the package can be "
304 "distracting. Fortunately, there is a simple email alias, "
305 "<literal><replaceable>package</replaceable>@&packages-host;</literal>, which "
306 "provides a way to email the maintainer, whatever their individual email "
307 "address (or addresses) may be. Replace <replaceable>package</replaceable> "
308 "with the name of a source or a binary package."
311 #. type: Content of: <chapter><section><para>
312 #: beyond-pkging.dbk:206
314 "You may also be interested in contacting the persons who are subscribed to a "
315 "given source package via <xref linkend=\"pkg-tracking-system\"/>. You can "
316 "do so by using the <literal><replaceable>package</replaceable>@&pts-host;</"
317 "literal> email address."
320 #. type: Content of: <chapter><section><title>
321 #: beyond-pkging.dbk:215
322 msgid "Dealing with inactive and/or unreachable maintainers"
325 #. type: Content of: <chapter><section><para>
326 #: beyond-pkging.dbk:217
328 "If you notice that a package is lacking maintenance, you should make sure "
329 "that the maintainer is active and will continue to work on their packages. "
330 "It is possible that they are not active any more, but haven't registered out "
331 "of the system, so to speak. On the other hand, it is also possible that "
332 "they just need a reminder."
335 #. type: Content of: <chapter><section><para>
336 #: beyond-pkging.dbk:224
338 "There is a simple system (the MIA database) in which information about "
339 "maintainers who are deemed Missing In Action is recorded. When a member of "
340 "the QA group contacts an inactive maintainer or finds more information about "
341 "one, this is recorded in the MIA database. This system is available in "
342 "<filename>/org/qa.debian.org/mia</filename> on the host <literal>qa.debian."
343 "org</literal>, and can be queried with the <command>mia-query</command> "
344 "tool. Use <command>mia-query --help</command> to see how to query the "
345 "database. If you find that no information has been recorded about an "
346 "inactive maintainer yet, or that you can add more information, you should "
347 "generally proceed as follows."
350 #. type: Content of: <chapter><section><para>
351 #: beyond-pkging.dbk:235
353 "The first step is to politely contact the maintainer, and wait a reasonable "
354 "time for a response. It is quite hard to define reasonable time, but it is "
355 "important to take into account that real life is sometimes very hectic. One "
356 "way to handle this would be to send a reminder after two weeks."
359 #. type: Content of: <chapter><section><para>
360 #: beyond-pkging.dbk:241
362 "If the maintainer doesn't reply within four weeks (a month), one can assume "
363 "that a response will probably not happen. If that happens, you should "
364 "investigate further, and try to gather as much useful information about the "
365 "maintainer in question as possible. This includes:"
368 #. type: Content of: <chapter><section><itemizedlist><listitem><para>
369 #: beyond-pkging.dbk:249
371 "The <literal>echelon</literal> information available through the <ulink url="
372 "\"&url-debian-db;\">developers' LDAP database</ulink>, which indicates when "
373 "the developer last posted to a Debian mailing list. (This includes mails "
374 "about uploads distributed via the &email-debian-devel-changes; list.) Also, "
375 "remember to check whether the maintainer is marked as on vacation in the "
379 #. type: Content of: <chapter><section><itemizedlist><listitem><para>
380 #: beyond-pkging.dbk:259
382 "The number of packages this maintainer is responsible for, and the condition "
383 "of those packages. In particular, are there any RC bugs that have been open "
384 "for ages? Furthermore, how many bugs are there in general? Another important "
385 "piece of information is whether the packages have been NMUed, and if so, by "
389 #. type: Content of: <chapter><section><itemizedlist><listitem><para>
390 #: beyond-pkging.dbk:268
392 "Is there any activity of the maintainer outside of Debian? For example, they "
393 "might have posted something recently to non-Debian mailing lists or news "
397 #. type: Content of: <chapter><section><para>
398 #: beyond-pkging.dbk:275
400 "A bit of a problem are packages which were sponsored — the maintainer is not "
401 "an official Debian developer. The <literal>echelon</literal> information is "
402 "not available for sponsored people, for example, so you need to find and "
403 "contact the Debian developer who has actually uploaded the package. Given "
404 "that they signed the package, they're responsible for the upload anyhow, and "
405 "are likely to know what happened to the person they sponsored."
408 #. type: Content of: <chapter><section><para>
409 #: beyond-pkging.dbk:283
411 "It is also allowed to post a query to &email-debian-devel;, asking if anyone "
412 "is aware of the whereabouts of the missing maintainer. Please Cc: the "
413 "person in question."
416 #. type: Content of: <chapter><section><para>
417 #: beyond-pkging.dbk:288
419 "Once you have gathered all of this, you can contact &email-mia;. People on "
420 "this alias will use the information you provide in order to decide how to "
421 "proceed. For example, they might orphan one or all of the packages of the "
422 "maintainer. If a package has been NMUed, they might prefer to contact the "
423 "NMUer before orphaning the package — perhaps the person who has done the NMU "
424 "is interested in the package."
427 #. type: Content of: <chapter><section><para>
428 #: beyond-pkging.dbk:296
430 "One last word: please remember to be polite. We are all volunteers and "
431 "cannot dedicate all of our time to Debian. Also, you are not aware of the "
432 "circumstances of the person who is involved. Perhaps they might be "
433 "seriously ill or might even have died — you do not know who may be on the "
434 "receiving side. Imagine how a relative will feel if they read the e-mail of "
435 "the deceased and find a very impolite, angry and accusing message!"
438 #. type: Content of: <chapter><section><para>
439 #: beyond-pkging.dbk:304
441 "On the other hand, although we are volunteers, we do have a responsibility. "
442 "So you can stress the importance of the greater good — if a maintainer does "
443 "not have the time or interest anymore, they should let go and give the "
444 "package to someone with more time."
447 #. type: Content of: <chapter><section><para>
448 #: beyond-pkging.dbk:310
450 "If you are interested in working in the MIA team, please have a look at the "
451 "<filename>README</filename> file in <filename>/org/qa.debian.org/mia</"
452 "filename> on <literal>qa.debian.org</literal> where the technical details "
453 "and the MIA procedures are documented and contact &email-mia;."
456 #. type: Content of: <chapter><section><title>
457 #: beyond-pkging.dbk:318
458 msgid "Interacting with prospective Debian developers"
461 #. type: Content of: <chapter><section><para>
462 #: beyond-pkging.dbk:320
464 "Debian's success depends on its ability to attract and retain new and "
465 "talented volunteers. If you are an experienced developer, we recommend that "
466 "you get involved with the process of bringing in new developers. This "
467 "section describes how to help new prospective developers."
470 #. type: Content of: <chapter><section><section><title>
471 #: beyond-pkging.dbk:326
472 msgid "Sponsoring packages"
475 #. type: Content of: <chapter><section><section><para>
476 #: beyond-pkging.dbk:328
478 "Sponsoring a package means uploading a package for a maintainer who is not "
479 "able to do it on their own. It's not a trivial matter, the sponsor must "
480 "verify the packaging and ensure that it is of the high level of quality that "
481 "Debian strives to have."
484 #. type: Content of: <chapter><section><section><para>
485 #: beyond-pkging.dbk:334
486 msgid "Debian Developers can sponsor packages. Debian Maintainers can't."
489 #. type: Content of: <chapter><section><section><para><orderedlist><listitem><para>
490 #: beyond-pkging.dbk:340
492 "The maintainer prepares a source package (<filename>.dsc</filename>) and "
493 "puts it online somewhere (like on <ulink url=\"http://mentors.debian.net/cgi-"
494 "bin/welcome\">mentors.debian.net</ulink>) or even better, provides a link to "
495 "a public VCS repository (see <xref linkend=\"servers-vcs\"/>) where the "
496 "package is maintained."
499 #. type: Content of: <chapter><section><section><para><orderedlist><listitem><para>
500 #: beyond-pkging.dbk:346
501 msgid "The sponsor downloads (or checkouts) the source package."
504 #. type: Content of: <chapter><section><section><para><orderedlist><listitem><para>
505 #: beyond-pkging.dbk:349
507 "The sponsor reviews the source package. If she finds issues, she informs the "
508 "maintainer and asks her to provide a fixed version (the process starts over "
512 #. type: Content of: <chapter><section><section><para><orderedlist><listitem><para>
513 #: beyond-pkging.dbk:354
515 "The sponsor could not find any remaining problem. She builds the package, "
516 "signs it, and uploads it to Debian."
519 #. type: Content of: <chapter><section><section><para>
520 #: beyond-pkging.dbk:337
522 "The process of sponsoring a package is: <placeholder type=\"orderedlist\" id="
526 #. type: Content of: <chapter><section><section><para>
527 #: beyond-pkging.dbk:360
529 "Before delving in the details of how to sponsor a package, you should ask "
530 "yourself whether adding the proposed package is beneficial to Debian."
533 #. type: Content of: <chapter><section><section><para>
534 #: beyond-pkging.dbk:364
536 "There's no simple rule to answer this question, it can depend on many "
537 "factors: is the upstream codebase mature and not full of security holes? Are "
538 "there pre-existing packages that can do the same task and how do they "
539 "compare to this new package? Has the new package been requested by users and "
540 "how large is the user base? How active are the upstream developers?"
543 #. type: Content of: <chapter><section><section><para>
544 #: beyond-pkging.dbk:371
546 "You should also ensure that the prospective maintainer is going to be a good "
547 "maintainer. Does she already have some experience with other packages? If "
548 "yes, is she doing a good job with them (check out some bugs)? Is she "
549 "familiar with the package and its programming language? Does she have the "
550 "skills needed for this package? If not, is she able to learn them?"
553 #. type: Content of: <chapter><section><section><para>
554 #: beyond-pkging.dbk:379
556 "It's also a good idea to know where she stands towards Debian: does she "
557 "agree with Debian's philosophy and does she intend to join Debian? Given how "
558 "easy it is to become a Debian Maintainer, you might want to only sponsor "
559 "people who plan to join. That way you know from the start that you won't "
560 "have to act as a sponsor indefinitely."
563 #. type: Content of: <chapter><section><section><section><title>
564 #: beyond-pkging.dbk:386
565 msgid "Sponsoring a new package"
568 #. type: Content of: <chapter><section><section><section><para>
569 #: beyond-pkging.dbk:388
571 "New maintainers usually have certain difficulties creating Debian packages — "
572 "this is quite understandable. They will do mistakes. That's why sponsoring a "
573 "brand new package into Debian requires a thorough review of the Debian "
574 "packaging. Sometimes several iterations will be needed until the package is "
575 "good enough to be uploaded to Debian. Thus being a sponsor implies being a "
579 #. type: Content of: <chapter><section><section><section><para>
580 #: beyond-pkging.dbk:396
582 "Don't ever sponsor a new package without reviewing it. The review of new "
583 "packages done by ftpmasters mainly ensures that the software is really free. "
584 "Of course, it happens that they stumble on packaging problems but they "
585 "really should not. It's your task to ensure that the uploaded package "
586 "complies with the Debian Free Software Guidelines and is of good quality."
589 #. type: Content of: <chapter><section><section><section><para><footnote><para>
590 #: beyond-pkging.dbk:409
592 "You can find more checks in the wiki where several developers share their "
593 "own <ulink url=\"http://wiki.debian.org/SponsorChecklist\">sponsorship "
594 "checklists</ulink>."
597 #. type: Content of: <chapter><section><section><section><para>
598 #: beyond-pkging.dbk:404
600 "Building the package and testing the software is part of the review, but "
601 "it's also not enough. The rest of this section contains a non-exhaustive "
602 "list of points to check in your review. <placeholder type=\"footnote\" id="
606 #. type: Content of: <chapter><section><section><section><itemizedlist><listitem><para>
607 #: beyond-pkging.dbk:416
609 "Verify that the upstream tarball provided is the same that has been "
610 "distributed by the upstream author (when the sources are repackaged for "
611 "Debian, generate the modified tarball yourself)."
614 #. type: Content of: <chapter><section><section><section><itemizedlist><listitem><para>
615 #: beyond-pkging.dbk:421
617 "Run <command>lintian</command> (see <xref linkend=\"lintian\"/>). It will "
618 "catch many common problems. Be sure to verify that any <command>lintian</"
619 "command> overrides setup by the maintainer is fully justified."
622 #. type: Content of: <chapter><section><section><section><itemizedlist><listitem><para>
623 #: beyond-pkging.dbk:426
625 "Run <command>licensecheck</command> (part of <xref linkend=\"devscripts\"/>) "
626 "and verify that <filename>debian/copyright</filename> seems correct and "
627 "complete. Look for license problems (like files with “All rights reserved” "
628 "headers, or with a non-DFSG compliant license). <command>grep -ri</command> "
629 "is your friend for this task."
632 #. type: Content of: <chapter><section><section><section><itemizedlist><listitem><para>
633 #: beyond-pkging.dbk:433
635 "Build the package with <command>pbuilder</command> (or any similar tool, see "
636 "<xref linkend=\"pbuilder\"/>) to ensure that the build-dependencies are "
640 #. type: Content of: <chapter><section><section><section><itemizedlist><listitem><para>
641 #: beyond-pkging.dbk:438
643 "Proofread <filename>debian/control</filename>: does it follow the best "
644 "practices (see <xref linkend=\"bpp-debian-control\"/>)? Are the dependencies "
648 #. type: Content of: <chapter><section><section><section><itemizedlist><listitem><para>
649 #: beyond-pkging.dbk:443
651 "Proofread <filename>debian/rules</filename>: does it follow the best "
652 "practices (see <xref linkend=\"bpp-debian-rules\"/>)? Do you see some "
653 "possible improvements?"
656 #. type: Content of: <chapter><section><section><section><itemizedlist><listitem><para>
657 #: beyond-pkging.dbk:448
659 "Proofread the maintainer scripts (<filename>preinst</filename>, "
660 "<filename>postinst</filename>, <filename>prerm</filename>, <filename>postrm</"
661 "filename>, <filename>config</filename>): will the <filename>preinst</"
662 "filename>/<filename>postrm</filename> work when the dependencies are not "
663 "installed? Are all the scripts idempotent (i.e. can you run them multiple "
664 "times without consequences)?"
667 #. type: Content of: <chapter><section><section><section><itemizedlist><listitem><para>
668 #: beyond-pkging.dbk:456
670 "Review any change to upstream files (either in <filename>.diff.gz</"
671 "filename>, or in <filename>debian/patches/</filename> or directly embedded "
672 "in the <filename>debian</filename> tarball for binary files). Are they "
673 "justified? Are they properly documented (with <ulink url=\"&url-dep3;"
674 "\">DEP-3</ulink> for patches)?"
677 #. type: Content of: <chapter><section><section><section><itemizedlist><listitem><para>
678 #: beyond-pkging.dbk:462
680 "For every file, ask yourself why the file is there and whether it's the "
681 "right way to achieve the desired result. Is the maintainer following the "
682 "best packaging practices (see <xref linkend=\"best-pkging-practices\"/>)?"
685 #. type: Content of: <chapter><section><section><section><itemizedlist><listitem><para>
686 #: beyond-pkging.dbk:468
688 "Build the packages, install them and try the software. Ensure you can remove "
689 "and purge the packages. Maybe test them with <command>piuparts</command>."
692 #. type: Content of: <chapter><section><section><section><para>
693 #: beyond-pkging.dbk:474
695 "If the audit did not reveal any problem, you can build the package and "
696 "upload it to Debian. Remember that even if you're not the maintainer, the "
697 "sponsor is still responsible of what he uploaded to Debian. That's why "
698 "you're encouraged to keep up with the package through the <xref linkend="
699 "\"pkg-tracking-system\"/>."
702 #. type: Content of: <chapter><section><section><section><para>
703 #: beyond-pkging.dbk:481
705 "Note that you should not need to modify the source package to put your name "
706 "in the <filename>changelog</filename> or in the <filename>control</filename> "
707 "file. The <literal>Maintainer</literal> field of the <filename>control</"
708 "filename> file and the <filename>changelog</filename> should list the person "
709 "who did the packaging, i.e. the sponsoree. That way she will get all the BTS "
713 #. type: Content of: <chapter><section><section><section><para>
714 #: beyond-pkging.dbk:487
716 "Instead you should instruct <command>dpkg-buildpackage</command> to use your "
717 "key for the signature. You do that with the <literal>-k</literal> option:"
720 #. type: Content of: <chapter><section><section><section><screen>
721 #: beyond-pkging.dbk:490
723 msgid "dpkg-buildpackage -k<replaceable>KEY-ID</replaceable>\n"
726 #. type: Content of: <chapter><section><section><section><para>
727 #: beyond-pkging.dbk:492
729 "If you use <command>debuild</command> and <command>debsign</command>, you "
730 "can even configure it permanently in <filename>~/.devscripts</filename>:"
733 #. type: Content of: <chapter><section><section><section><programlisting>
734 #: beyond-pkging.dbk:495
736 msgid "DEBSIGN_KEYID=<replaceable>KEY-ID</replaceable>\n"
739 #. type: Content of: <chapter><section><section><section><title>
740 #: beyond-pkging.dbk:500
741 msgid "Sponsoring an update of an existing package"
744 #. type: Content of: <chapter><section><section><section><para>
745 #: beyond-pkging.dbk:502
747 "You will usually assume that the package has already gone through a full "
748 "review. So instead of doing it again, you will carefully analyze the "
749 "difference between the current version and the new version prepared by the "
750 "maintainer. If you have not done the initial review yourself, you might "
751 "still want to have a more deeper look just in case the initial reviewer was "
755 #. type: Content of: <chapter><section><section><section><para>
756 #: beyond-pkging.dbk:510
758 "To be able to analyze the difference you need both versions. Download the "
759 "current version of the source package (with <command>apt-get source</"
760 "command>) and rebuild it (or download the current binary packages with "
761 "<command>aptitude download</command>). Download the source package to "
762 "sponsor (usually with <command>dget</command>)."
765 #. type: Content of: <chapter><section><section><section><para>
766 #: beyond-pkging.dbk:517
768 "Read the new changelog entry, it should tell you what to expect during the "
769 "review. The main tool you will use is <command>debdiff</command> (provide by "
770 "the <systemitem role=\"package\">devscripts</systemitem> package), you can "
771 "run it with two source packages (<filename>.dsc</filename> files), or two "
772 "binary packages, or two <filename>.changes</filename> files (it will then "
773 "compare all the binary packages listed in the <filename>.changes</filename>)."
776 #. type: Content of: <chapter><section><section><section><para>
777 #: beyond-pkging.dbk:524
779 "If you compare the source packages (excluding upstream files in the case of "
780 "a new upstream version, for example by filtering the output of "
781 "<command>debdiff</command> with <command>filterdiff -i '*/debian/*'</"
782 "command>), you must understand all the changes you see and they should be "
783 "properly documented in the Debian changelog."
786 #. type: Content of: <chapter><section><section><section><para>
787 #: beyond-pkging.dbk:531
789 "If everything is fine, build the package and compare the binary packages to "
790 "verify that the changes on the source package have no unexpected "
791 "consequences (like some files dropped by mistake, missing dependencies, "
795 #. type: Content of: <chapter><section><section><section><para>
796 #: beyond-pkging.dbk:537
798 "You might want to check out the Package Tracking System (see <xref linkend="
799 "\"pkg-tracking-system\"/>) to verify if the maintainer has not missed "
800 "something important. Maybe there are translations updates sitting in the BTS "
801 "that could have been integrated. Maybe the package has been NMUed and the "
802 "maintainer forgot to integrate the changes from the NMU in his package. "
803 "Maybe there's a release critical bug that he has left unhandled and that's "
804 "blocking migration to <literal>testing</literal>. Whatever. If you find "
805 "something that she could have done (better), it's time to tell her so that "
806 "she can improve for next time, and so that she has a better understanding of "
807 "her responsibilities."
810 #. type: Content of: <chapter><section><section><section><para>
811 #: beyond-pkging.dbk:549
813 "If you have found no major problem, upload the new version. Otherwise ask "
814 "the maintainer to provide you a fixed version."
817 #. type: Content of: <chapter><section><section><title>
818 #: beyond-pkging.dbk:556
819 msgid "Advocating new developers"
822 #. type: Content of: <chapter><section><section><para>
823 #: beyond-pkging.dbk:558
825 "See the page about <ulink url=\"&url-newmaint-advocate;\">advocating a "
826 "prospective developer</ulink> at the Debian web site."
829 #. type: Content of: <chapter><section><section><title>
830 #: beyond-pkging.dbk:565
831 msgid "Handling new maintainer applications"
834 #. type: Content of: <chapter><section><section><para>
835 #: beyond-pkging.dbk:567
837 "Please see <ulink url=\"&url-newmaint-amchecklist;\">Checklist for "
838 "Application Managers</ulink> at the Debian web site."