<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.151 $">
+ <!entity cvs-rev "$Revision: 1.155 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
<p>
There is infrastructure and several tools to help automate the package
porting. This section contains a brief overview of this automation and
-portingto these tools; see the package documentation or references for
+porting to these tools; see the package documentation or references for
full information.</p>
<sect2>
name="Debian Policy">, which defines explicit baseline requirements
which all Debian packages must fulfill. Yet there is also a shared
history of experience which goes beyond the Debian Policy, an
-accumulatation of years of experience in packaging. Many very
+accumulation of years of experience in packaging. Many very
talented people have created great tools, tools which help you, the
Debian maintainer, create and maintain excellent packages.
<p>
<package>debmake</package>, were "monolithic": you couldn't pick and
choose which part of the helper you found useful, but had to use the
helper to do everything. <package>debhelper</package>, however, is a
-number of sep
erate little <prgn>dh_*</prgn> programs. For instance,
-<prgn>dh_installman</prgn> installs and compresses manpages,
+number of sep
arate little <prgn>dh_*</prgn> programs. For instance,
+<prgn>dh_installman</prgn> installs and compresses man pages,
<prgn>dh_installmenu</prgn> installs menu files, and so on. Thus, it
offers enough flexibility to be able to use the little helper scripts,
where useful, in conjunction with hand-crafted commands in
learn its expectations and behavior.
<p>
Some people feel that vanilla <file>debian/rules</file> files are
-better, since you don't have to learn the intricies of any helper
+better, since you don't have to learn the intricacies of any helper
system. This decision is completely up to you. Use what works for
you. Many examples of vanilla <file>debian/rules</file> files are
available at <url id="&url-rules-files;">.
<prgn>install</prgn> (vanilla approach) or <prgn>dh_install</prgn>
(from <package>debhelper</package>). Be sure to check the different
permutations of the various packages, ensuring that you have the
-inter-package dependancies set right in <file>debian/control</file>.
+inter-package dependencies set right in <file>debian/control</file>.
<p>
The first case is a bit more difficult since it involves multiple
recompiles of the same software but with different configure
<p>
Keep the maintainer scripts as simple as possible. We suggest you use
pure POSIX shell scripts. Remember, if you do need any bash features,
-the maintainer script must have a bash shbang line. Posix shell or
+the maintainer script must have a bash sh-bang line. POSIX shell or
Bash are preferred to Perl, since they enable
<package>debhelper</package> to easily add bits to the scripts.
<p>
package is completely gone, that is, it must remove any files created,
directly or indirectly, in any maintainer script.
<p>
-If you need to check for the existance of a command, you should use
+If you need to check for the existence of a command, you should use
something like
<example>if [ -x /usr/sbin/install-docs ]; then ...</example>
-If you don't wish to hardcode the path of the command in your
+If you don't wish to hard-code the path of the command in your
maintainer script, the following POSIX-compliant shell function may
help:
<sect1 id="bpp-upstream-info">
<heading>Upstream home page</heading>
<p>
-We recommend that you add the URL for the package's homepage to the
-package description in <file>debian/control</file>, and a link to a
-screenshot, if one is handy. This information should be added at the
+We recommend that you add the URL for the package's home page to the
+package description in <file>debian/control</file>. This information
+should be added at the
end of description, using the following format:
<example> .
- Homepage: http://some-project.some-place.org/
- Screenshot: http://some-project.some-place.org/</example>
+ Homepage: http://some-project.some-place.org/</example>
Note the spaces prepending the line, which serves to break the lines
correctly. To see an example of how this displays, see <url
<p>
If there is no home page for the software, this should naturally be
left empty.
+ <p>
+Note that we expect this field will eventually be replaced by a proper
+<file>debian/control</file> field understood by <prgn>dpkg</prgn> and
+<tt>&packages-host;</tt>. If you don't want to bother migrating the
+home page from the description to this field, you should probably wait
+until that is available.</p>
</sect1>
</sect>
and provide that in your CVS area.
<p>
If you maintain XML or SGML documentation, we suggest that you isolate
-any language-independant information and define those as entities in a
+any language-independent information and define those as entities in a
separate file which is included by all the different
translations. This makes it much easier, for instance, to keep URLs
up-to-date across multiple files.
especially on more volatile architectures. Some very good packaging
practices for any package using <prgn>autoconf</prgn> and/or
<prgn>automake</prgn> have been synthesized in
-&file-bpp-autotools;. You're strongly encouraged to read this file and
+&file-bpp-autotools; from the <package>autotools-dev</package>
+package. You're strongly encouraged to read this file and
to follow the given recommendations.
Good practices for library packaging have been grouped in
<url id="&url-libpkg-guide;" name="the library packaging guide">.
+
+ <sect1 id="bpp-docs">Documentation
+ <p>
+Be sure to follow the <url id="&url-debian-policy;ch-docs.html"
+ name="Policy on documentation">.</p>
+ <p>
+If your package contains documentation built from XML or SGML, we
+recommend you not ship the XML or SGML source in the binary
+package(s). If users want the source of the documentation, they
+should retrieve the source package.</p>
+ <p>
+Policy specifies that documentation should be shipped in HTML format.
+We also recommend shipping documentation in PDF and plain text format if
+convenient and quality output is possible. However, it is generally
+not appropriate to ship plain text versions of documentation whose source
+format is HTML.</p>
+ <p>
+Major shipped manuals should register themselves with
+<package>doc-base</package> on installation. See the
+<package>doc-base</package> package documentation for more
+information.</p>
+
+
<sect1 id="bpp-other">Specific types of packages
<p>
Several specific types of packages have special sub-policies and
If someone doesn't feel confident with an NMU, he should just send a patch
to the BTS. It's far better than a broken NMU.
- <sect id="mia-qa">Dealing with unreachable maintainers
- <p>
-If you notice that a package is lacking maintenance, you should
-make sure the maintainer is active and will continue to work on
-his packages. Try contacting him yourself.
- <p>
-If you do not get a reply after a few weeks you should collect all
-useful information about this maintainer. Start by logging into
-the <url id="&url-debian-db;" name="Debian Developer's Database">
-and doing a full search to check whether the maintainer is on vacation
-and when they were last seen. Collect any important package names
-they maintain and any Release Critical bugs filed against them.
- <p>
-Send all this information to &email-debian-qa;, in order to let the
-QA people do whatever is needed.
<sect id="contacting-maintainers">Contacting other maintainers
<p>
email address.
+ <sect id="mia-qa">Dealing with inactive and/or unreachable maintainers
+ <p>
+If you notice that a package is lacking maintenance, you should
+make sure that the maintainer is active and will continue to work on
+their packages. It is possible that they are not active any more, but
+haven't registered out of the system, so to speak. On the other hand,
+it is also possible that they just need a reminder.
+ <p>
+The first step is to politely contact the maintainer, and wait for a
+response, for a reasonable time. It is quite hard to define "reasonable
+time", but it is important to take into account that real life is sometimes
+very hectic. One way to handle this would be send a reminder after two
+weeks.
+ <p>
+If the maintainer doesn't reply within four weeks (a month), one can
+assume that a response will probably not happen. If that happens, you
+should investigate further, and try to gather as much useful information
+about the maintainer in question as possible. This includes:
+ <p>
+ <list>
+ <item>The "echelon" information available through the
+ <url id="&url-debian-db;" name="developers' LDAP database">,
+ which indicates when's the last time a developer has posted to
+ a Debian mailing list. (This includes uploads via
+ debian-*-changes lists.) Also, remember to check whether the
+ maintainer is marked as "on vacation" in the database.
+
+ <item>The number of packages this maintainer is responsible for,
+ and the condition of those packages. In particular, are there
+ any RC bugs that have been open for ages? Furthermore, how
+ many bugs are there in general? Another important piece of
+ information is whether the packages have been NMUed, and if
+ so, by whom?
+
+ <item>Is there any activity of the maintainer outside of Debian?
+ For example, they might have posted something recently to
+ non-Debian mailing lists or news groups.
+ </list>
+ <p>
+One big problem are packages which were sponsored -- the maintainer is not
+an official Debian developer. The echelon information is not available for
+sponsored people, for example, so you need to find and contact the Debian
+developer who has actually uploaded the package. Given that they signed the
+package, they're responsible for the upload anyhow, and should know what
+happened to the person they sponsored.
+ <p>
+Once you have gathered all of this, you can contact &email-debian-qa;.
+People on this alias will use the information you provided in order to
+decide how to proceed. For example, they might orphan one or all of the
+packages of the maintainer. If a packages has been NMUed, they might prefer
+to contact the NMUer before orphaning the package -- perhaps the person who
+has done the NMU is interested in the package.
+ <p>
+One last word: please remember to be polite. We are all volunteers and
+cannot dedicate all of our time to Debian. Also, you are not aware of the
+circumstances of the person who is involved. Perhaps they might be
+seriously ill or might even had died -- you do not know who may be on the
+receiving side -- imagine how a relative will feel if they read the e-mail
+of the deceased and find a very impolite, angry and accusing message!)
+ <p>
+On the other hand, although we are volunteers, we do have a responsibility.
+So you can stress the importance of the greater good -- if a maintainer does
+not have the time or interest anymore, they should "let go" and give the
+package to someone with more time.
+
+
<sect id="newmaint">
<heading>Interacting with prospective Debian developers</heading>
<p>
complete list of available scripts.</p>
</sect1>
+ <sect1 id="autotools-dev">
+ <heading><package>autotools-dev</package></heading>
+ <p>
+Contains best practices for people maintaining packages that use
+<prgn>autoconf</prgn> and/or <prgn>automake</prgn>. Also contains
+canonical <file>config.sub</file> and <file>config.guess</file> files
+which are known to work on all Debian ports.</p>
+ </sect1>
+
+ <sect1 id="dpkg-repack">
+ <heading><package>dpkg-repack</package></heading>
+ <p>
+<prgn>dpkg-repack</prgn> creates Debian package file out of a package
+that has already been installed. If any changes have been made to the
+package while it was unpacked (e.g., files in <file>/etc</file> were
+modified), the new package will inherit the changes.</p>
+ <p>
+This utility can make it easy to copy packages from one computer to
+another, or to recreate packages that are installed on your system
+but no longer available elsewhere, or to store the current state of a
+package before you upgrade it.</p>
+ </sect1>
+
+ <sect1 id="alien">
+ <heading><package>alien</package></heading>
+ <p>
+<prgn>alien</prgn> converts binary packages between various packaging
+formats, including Debian, RPM (RedHat), LSB (Linux Standard Base),
+Solaris and Slackware packages.</p>
+ </sect1>
+
+ <sect1 id="debsums">
+ <heading><package>debsums</package></heading>
+ <p>
+<prgn>debsums</prgn> checks installed packages against their MD5 sums.
+Note that not all packages have MD5 sums, since they aren't required
+by Policy.</p>
+ </sect1>
+
<sect1 id="dpkg-dev-el">
<heading><package>dpkg-dev-el</package></heading>
<p>
<prgn>dpkg-buildpackage</prgn> and <prgn>dpkg-shlibdeps</prgn> is
enhanced to support cross-compiling.
</sect1>
+
+
+ <sect id="tools-doc">
+ <heading>Documentation and information</heading>
+ <p>
+The following packages provide information for maintainers or help
+with building documentation.
+
+ <sect1 id="debiandoc-sgml">
+ <heading><package>debiandoc-sgml</package></heading>
+ <p>
+<package>debiandoc-sgml</package> provides the DebianDoc SGML DTD,
+which is commonly used for Debian documentation. This manual, for
+instance, is written in DebianDoc. It also provides scripts for
+building and styling the source to various output formats.</p>
+ <p>
+Documentation for the DTD can be found in the
+<package>debiandoc-sgml-doc</package> package.</p>
+ </sect1>
+
+ <sect1 id="debian-keyring">
+ <heading><package>debian-keyring</package></heading>
+ <p>
+Contains the public GPG and PGP keys of Debian developers. See <ref
+id="key-maint"> and the package documentation for more
+information.</p>
+ </sect1>
+
+ <sect1 id="debview">
+ <heading><package>debview</package></heading>
+ <p>
+<package>debview</package> provides an Emacs mode for viewing Debian
+binary packages. This lets you examine a package without unpacking
+it.</p>
+ </sect1>
</sect>
<!-- FIXME: add the following
- alien
- dpkg-repack
- debsums
- debiandoc-sgml, debiandoc-sgml-doc
- debian-keyring
questionable:
ucf
dpkg-awk
grep-dctrl
- debview
d-shlibs
wajig
magpie
~ianmdlvl / developers-reference.git / blobdiff