<para>
Make sure the bug is not already filed against a package. Each package has a
bug list easily reachable at
-<literal>http://&bugs-host;/<replaceable>packagename</replaceable></literal>
+<literal>http://&bugs-host;/<replaceable>packagename</replaceable></literal>.
Utilities like <citerefentry> <refentrytitle>querybts</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> can also provide you with this
information (and <command>reportbug</command> will usually invoke
The process of sponsoring a package is:
<orderedlist numeration="arabic">
<listitem>
-<para>The maintainer prepares a source package (.dsc) and puts it online
-somewhere (like on mentors.debian.net). Or even better, she provides
+<para>The maintainer prepares a source package (<filename>.dsc</filename>) and puts it online
+somewhere (like on <ulink url="http://mentors.debian.net/cgi-bin/welcome">mentors.debian.net</ulink>) or even better, provides
a link to a public VCS repository (see <xref linkend="servers-vcs"/>) where
the package is maintained.</para>
</listitem>
<para>The sponsor downloads (or checkouts) the source package.</para>
</listitem>
<listitem>
-<para>The sponsor reviews the source package. If she finds issues, she
-informs the maintainer and asks her to provide a fixed version (the
+<para>The sponsor reviews the source package. If they find issues, they
+inform the maintainer and ask them to provide a fixed version (the
process starts over at step 1).</para>
</listitem>
<listitem>
-<para>The sponsor could not find any remaining problem. She builds the
-package, signs it, and uploads it to Debian.</para>
+<para>The sponsor could not find any remaining problem. They build the
+package, sign it, and upload it to Debian.</para>
</listitem>
</orderedlist>
</para>
<para>
-But before delving in the details of how to sponsor a package, you should
+Before delving in the details of how to sponsor a package, you should
ask yourself whether adding the proposed package is beneficial to Debian.
</para>
<para>
factors: is the upstream codebase mature and not full of security holes?
Are there pre-existing packages that can do the same task and how do they
compare to this new package? Has the new package been requested by users
-and how large is the userbase? How active are the upstream developers?
+and how large is the user base? How active are the upstream developers?
</para>
<para>
You should also ensure that the prospective maintainer is going
-to be a good maintainer. Does she already have some experience with other
-packages? If yes, is she doing a good job with them (check out some bugs)?
-Is she familiar with the package and its programming language?
-Does she have the skills needed for this package? If not, is she able
+to be a good maintainer. Do they already have some experience with other
+packages? If yes, are they doing a good job with them (check out some bugs)?
+Are they familiar with the package and its programming language?
+Do they have the skills needed for this package? If not, are they able
to learn them?
</para>
<para>
-It's also a good idea to know where she stands towards Debian: does
-she agree with Debian's philosophy and does she intend to join Debian?
+It's also a good idea to know where they stand with respect to Debian: do
+they agree with Debian's philosophy and do they intend to join Debian?
Given how easy it is to become a Debian Maintainer, you might want
to only sponsor people who plan to join. That way you know from the start
that you won't have to act as a sponsor indefinitely.
list of points to check in your review.
<footnote>
<para>
-You can find more checks in the wiki: several developers share their own
-sponsorship checklists at <ulink url="http://wiki.debian.org/SponsorChecklist"/>.
+You can find more checks in the wiki where several developers share their own
+<ulink url="http://wiki.debian.org/SponsorChecklist">sponsorship checklists</ulink>.
</para>
</footnote>
</para>
Debian, generate the modified tarball yourself).</para>
</listitem>
<listitem>
-<para>Run lintian (see <xref linkend="lintian"/>). It will catch many common
-problems. Be sure to verify that any lintian overrides setup by the
+<para>Run <command>lintian</command> (see <xref linkend="lintian"/>). It will catch many common
+problems. Be sure to verify that any <command>lintian</command> overrides setup by the
maintainer is fully justified.</para>
</listitem>
<listitem>
-<para>Run licensecheck (part of <xref linkend="devscripts"/>) and verify that
+<para>Run <command>licensecheck</command> (part of <xref linkend="devscripts"/>) and verify that
<filename>debian/copyright</filename> seems correct and complete. Look for
license problems (like files with “All rights reserved”
headers, or with a non-DFSG compliant license). <command>grep -ri</command>
is your friend for this task.</para>
</listitem>
<listitem>
-<para>Build the package with pbuilder (or any similar tool, see <xref
+<para>Build the package with <command>pbuilder</command> (or any similar tool, see <xref
linkend="pbuilder"/>) to ensure that the build-dependencies are
complete.</para>
</listitem>
possible improvements?</para>
</listitem>
<listitem>
-<para>Proofread the maintainer scripts (preinst, postinst, prerm, postrm,
-config): will the preinst/postrm work when the dependencies are not
+<para>Proofread the maintainer scripts (<filename>preinst</filename>,
+<filename>postinst</filename>, <filename>prerm</filename>,
+<filename>postrm</filename>, <filename>config</filename>): will the
+<filename>preinst</filename>/<filename>postrm</filename> work when the dependencies are not
installed? Are all the scripts idempotent (i.e. can you run them multiple
times without consequences)?</para>
</listitem>
<listitem>
-<para>Review any change to upstream files (either in .diff.gz, or in
-<filename>debian/patches/</filename> or directly embedded in the debian
+<para>Review any change to upstream files (either in <filename>.diff.gz</filename>, or in
+<filename>debian/patches/</filename> or directly embedded in the <filename>debian</filename>
tarball for binary files). Are they justified? Are they properly
documented (with <ulink url="&url-dep3;">DEP-3</ulink> for patches)?</para>
</listitem>
</listitem>
<listitem>
<para>Build the packages, install them and try the software. Ensure you can
-remove and purge the packages. Maybe test them with piuparts.
+remove and purge the packages. Maybe test them with <command>piuparts</command>.
</para>
</listitem>
</itemizedlist>
<para>
If the audit did not reveal any problem, you can build the package and
-upload it to Debian. But remember that even if you're not the maintainer,
-the sponsor is still responsible of what he uploaded to Debian. That's
+upload it to Debian. Remember that even if you're not the maintainer,
+as a sponsor you are still responsible for what you upload to Debian. That's
why you're encouraged to keep up with the package through the
<xref linkend="pkg-tracking-system"/>.
</para>
<para>
-Note that you should not need to modifiy the source package to put your name
-in the changelog or in the control file. The <literal>Maintainer</literal>
+Note that you should not need to modify the source package to put your name
+in the <filename>changelog</filename> or in the <filename>control</filename> file. The <literal>Maintainer</literal>
field of the <filename>control</filename> file and the
<filename>changelog</filename> should list the person who did the
-packaging, i.e. the sponsoree. That way she will get all the BTS mail.
+packaging, i.e. the sponsoree. That way they will get all the BTS mail.
</para>
-<para>Instead you should instruct dpkg-buildpackage to use your key for
-the signature. You do that with the -k option:</para>
+<para>Instead you should instruct <command>dpkg-buildpackage</command> to use your key for
+the signature. You do that with the <literal>-k</literal> option:</para>
<screen>
dpkg-buildpackage -k<replaceable>KEY-ID</replaceable>
</screen>
-<para>If you use debuild and debsign, you can even configure it permanently
+<para>If you use <command>debuild</command> and <command>debsign</command>, you can even configure it permanently
in <filename>~/.devscripts</filename>:</para>
<programlisting>
DEBSIGN_KEYID=<replaceable>KEY-ID</replaceable>
<para>
Read the new changelog entry, it should tell you what to expect during the
review. The main tool you will use is <command>debdiff</command> (provide by
-the devscripts package), you can run it with two source packages (.dsc
-files), or two binary packages, or two .changes files (it will then
-compare all the binary packages listed in the .changes).
+the <systemitem role="package">devscripts</systemitem> package), you can run it with two source packages (<filename>.dsc</filename>
+files), or two binary packages, or two <filename>.changes</filename> files (it will then
+compare all the binary packages listed in the <filename>.changes</filename>).
</para>
<para>
If you compare the source packages (excluding upstream files in the case
-of a new upstream version, for example by filtering the output of debdiff
+of a new upstream version, for example by filtering the output of <command>debdiff</command>
with <command>filterdiff -i '*/debian/*'</command>), you must understand all the
changes you see and they should be properly documented in the Debian
changelog.
maintainer has not missed something important. Maybe there are translations
updates sitting in the BTS that could have been integrated. Maybe the package
has been NMUed and the maintainer forgot to integrate the changes from the
-NMU in his package. Maybe there's a release critical bug that he has left
-unhandled and that's blocking migration to testing. Whatever. If you find
-something that she could have done (better), it's time to tell her so that
-she can improve for next time. And so that she has a better understanding
-of her responsibilities.
+NMU into their package. Maybe there's a release critical bug that they have
+left unhandled and that's blocking migration to <literal>testing</literal>.
+If you find something that they could have done (better), it's time to tell
+them so that they can improve for next time, and so that they have a better
+understanding of their responsibilities.
</para>
<para>
If you have found no major problem, upload the new version. Otherwise
~ianmdlvl / developers-reference.git / blobdiff