maint-guide: propuestas de mejoras del original
Hola,
He traducido al inglés las mejoras a la maint-guide. Os adjunto el
archivo de diferencias. Si no tengo noticias vuestras, se lo enviaré a
Osamu Aoki.
Saludos,
I. De Marchi
--- maint-guide.en.sgml 2010-12-19 19:23:23.000000000 +0100
+++ maint-guide-mejoras.en.traduc.sgml 2011-01-26 18:07:46.000000000 +0100
@@ -287,7 +287,7 @@
<list>
<item><strong>upstream author</strong>: The person who made the original
- program.
+ program (or original documents in the case of documentation packages).
<item><strong>upstream maintainer</strong>: The person who currently
maintains the program.
@@ -310,7 +310,7 @@
</list>
- <p>There are several version names used around Debian.
+ <p>There are several version (see <ref id="namever">) names used around Debian.
<list>
<item><strong>upstream source version</strong>: The upstream source version is referred as <tt><var>version</var></tt>.
@@ -334,7 +334,8 @@
discouraged by this. If it is useful to others, you can still upload your
package either as a <strong>maintainer</strong> through a
<strong>sponsor</strong> or as a <strong>Debian Maintainer</strong>.
- See <url name="Debian New Maintainers" id="&newmaint;"> for more.
+ See <url name="Debian New Maintainers" id="&newmaint;">
+ and <url id="&mentors-faq;" name="Debian Mentors FAQ"> for more.
<p>Please note that you do not need to create any new package to
become an official Debian Developer. Contributing to the existing
@@ -350,7 +351,9 @@
<file>/usr/share/doc/debian</file>, <file>&autotools-dev;</file>,
<file>/usr/share/doc/<var>package</var>/*</file>
files and the <prgn>man</prgn>/<prgn>info</prgn> pages for all the programs mentioned in this document.
- See all the information at <url id="&nm-home;">.
+ See all the information at <url id="&nm-home;">
+ <footnote><p>restricted access to persons who are in the program
+ to access DD or DM.</p></footnote> and <url id="&mentors-faq;">.
<p>Making a small test package is good way to learn details of packaging.
Inspecting existing well maintained packages is the best way to learn how other
@@ -362,8 +365,9 @@
developers will gladly help you, but do read at least some of the
documentation before asking a question!
- <p>See <url id="http://lists.debian.org/debian-mentors/";> for more
- information about this mailing list.
+ <p>See <url id="http://lists.debian.org/debian-mentors/";>
+ (for more information about this mailing list)
+ or IRC channel #debian-mentors.
<p>When you receive
a bug report (yes, actual bug reports!), you will know that it is time for you
@@ -389,7 +393,8 @@
<chapt id="first">First steps
- <p>Let's try to make your own package (or, better even, adopt an existing one).
+ <p>Let's try to make your own package (or, better even, adopt an existing one
+ , see <url id="http://wnpp.debian.net/"; name="Debian Packages that Need Lovin'">).
<sect id="choose">Choose your program
@@ -408,6 +413,7 @@
at <url name="Debian Bug report logs: Bugs in package wnpp in unstable" id="http://bugs.debian.org/wnpp";>).
You may also adopt a package for which the corresponding maintainer has filed
a "Request for Adoption" (<strong>RFA</strong>).
+ See <url id="http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=594398";> for an example.
<p>Several different views of orphaned or RFA'ed packages are available at:
<list>
@@ -427,12 +433,27 @@
You can do that in various ways.
<list>
<item>taking over orphaned, yet actively used, packages
+ (look at the Popularity Contest Stats of the package in
+ <url id="http://qa.debian.org/popcon.php";>)
<item>joining <url name="packaging teams" id="http://wiki.debian.org/Teams";>
<item>triaging bugs of very popular packages
<item>preparing <url name="QA or NMU uploads" id="http://www.debian.org/doc/developers-reference/pkgs.html#nmu-qa-upload";>
+ <footnote><p>QA packages are maintained by the Debian Quality Group
+ and they are orphans, and NMU are packages that do not currently
+ have an maintainer.</p></footnote>.
</list>
- <p>If you are able to adopt the package, get the sources (with something
+ <p>If you are able to adopt the package
+ <footnote><p>The most direct way to adopt an orphaned package
+ is to consult the list of orphaned packages <url id="http://wnpp.debian.net/?type[]=O&project=&description=&owner[]=yes&owner[]=no&col[]=dust&col[]=type&col[]=description&col[]=installs&sort=project";>.
+ In these lists, package name refers directly to the bug report
+ states that as an orphan. If you decide to adopt a package,
+ send an email to the list with the number of bug report requesting
+ the change of title of the error report
+ (see <url id="http://www.debian.org/devel/wnpp/index.html#howto-o";>).
+ With this notification, the other contributors know that you're
+ working on the package.</p></footnote>
+ , get the sources (with something
like "<tt>apt-get source <var>packagename</var></tt>") and examine them. This document
unfortunately doesn't include comprehensive information about adopting
packages. Thankfully you shouldn't have a hard time figuring out how the
@@ -472,7 +493,14 @@
</list>
If you are unsure about where it should go, post the license text on
- <url id="http://lists.debian.org/debian-legal/"; name="debian-legal@lists.debian.org"> and ask for advice.
+ <url id="http://lists.debian.org/debian-legal/"; name="debian-legal@lists.debian.org"> and ask for advice
+ <footnote><p>English is the official language of Debian. You
+ must use this language in the messages you send to mailing lists
+ (even though you know the recipient speaks your language). However,
+ there are specific mailing lists for many languages. You can see the
+ current mailing list to <url id=\"http://lists.debian.org/\";>.
+ It will also be useful to read this
+ <url id=\"http://www.debian.org/MailingLists/\";>.</p></footnote>.
</item>
<item>That program certainly should <strong>not</strong> run setuid root, or
@@ -526,7 +554,7 @@
unpack it with appropriate tools and repack it, too.
<p>As an example, I'll use a program called <prgn>gentoo</prgn>, an X GTK+ file
- manager.<footnote>This program is already packaged. Current version 0.15.3 has changed
+ manager.<footnote>This program is already packaged. Current version 0.19.8 has changed
substantially from the version 0.9.12 in the following examples.</footnote>
<p>Create a subdirectory under your home directory named <file>debian</file> or <file>deb</file>
@@ -555,7 +583,11 @@
directory; you won't be doing that, but more on that later in <ref
id="destdir">).
- <p>Simple programs come with a <file>Makefile</file> file in them and can be
+ <p>The process varies from program to program, but most modern
+ programs come with a script <file>configure</file> to configure
+ the sources for your system and ensures that the system is able
+ to compile.
+ Simple programs come with a <file>Makefile</file> file in them and can be
compiled simply with "<tt>make</tt>". Some of them support
"<tt>make check</tt>", which runs included self-checks. Installation to the
destination directories is usually done with "<tt>make install</tt>".
@@ -829,7 +861,16 @@
install gentoorc-example $(HOME)/.gentoorc
</example>
-<p>Ask <prgn>quilt</prgn> to refresh the patch to create <file>debian/patches/fix-gentoo-target.patch</file> and add its description.
+<p>Ask <prgn>quilt</prgn> to refresh the patch to create <file>debian/patches/fix-gentoo-target.patch</file> and add its description
+<footnote><p>It is advised that after the execution of each order,
+ you carefully consider the changes. In this example, the
+ <file>debian/patches/fix-gentoo-target.patch</file> file is generated:
+ which is a text file that contains the changes into the
+ <file>Makefile</file> file. Lines to delete are preceded by
+ a sign "-" and then the new lines are preceded by a '+'.At the head
+ of the patch file is the description of the patch. The descriptions
+ must be in English. See <url name="Patch Tagging Guidelines" id="http://dep.debian.net/deps/dep3/";>
+ for more details.</p></footnote>.
<example>
$ quilt refresh
@@ -901,6 +942,13 @@
strings like
<tt>/home/me/deb/<var>package</var>-<var>version</var>/usr/share/<var>package</var></tt>
into the package file.
+ The <file>.deb</file> files are compressed files. If you look
+ the <file>.deb</file> file with a compressed files management program
+ you will see a zip file containing "data.tar.gz" which contains
+ a replica of the directory structure starting at the root directory.
+ The analysis of the contents of the "debian" directory after
+ the construction of the <file>.deb</file> file and the content
+ of the <file>.deb</file> package file can you help to understand the process.
<p>Here's the relevant part of <package>gentoo</package>'s
<file>Makefile</file> file
@@ -970,7 +1018,7 @@
starts with <tt>install:</tt>, that will usually work) and rename all references
to directories other than ones defined at the top of the <file>Makefile</file>.
- <p>After your upstream bug fix, <package>gentoo</package>'s install target said:
+ <p>Before your upstream bug fix, <package>gentoo</package>'s install target said:
<example>
install: gentoo-target
@@ -1231,14 +1279,16 @@
<p>Line 11 shows one of the most powerful features of the Debian packaging
system. Packages can relate to each other in various ways. Apart from
<tt>Depends</tt>, other relationship fields are <tt>Recommends</tt>, <tt>Suggests</tt>,
- <tt>Pre-Depends</tt>, <tt>Breaks</tt>, <tt>Conflicts</tt>, <tt>Provides</tt>, and <tt>Replaces</tt>.
+ <tt>Pre-Depends</tt>, <tt>Breaks</tt>, <tt>Conflicts</tt>, <tt>Provides</tt>, and <tt>Replaces</tt>
+ See <url id="http://www.debian.org/doc/FAQ/ch-pkg_basics.en.html#s-depends"; name="The Debian GNU/Linux FAQ">.
<p>The package management tools usually behave the same way when dealing
with these relations; if not, it will be explained.
(see <manref name="dpkg" section="8">, <manref name="dselect" section="8">,
<manref name="apt" section="8">, <manref name="aptitude" section="1"> etc.)
- <p>This is what the dependencies mean:
+ <p>This is what the dependencies mean
+ (see <url id="http://www.debian.org/doc/debian-policy/ch-relationships.html";>):
<p><list>
<item><tt>Depends</tt>
@@ -1351,12 +1401,16 @@
which gives more details about the package. Column 1 of each line should
be empty. There must be no blank lines, but you can put a single "<tt>.</tt>" (dot)
in a column to simulate that. Also, there must be no more than one blank
- line after the long description.
+ line after the long description <footnote><p>These descriptions are in English.
+ Yet there is an ongoing project to facilitate translation
+ (<url id=\"http://www.debian.org/intl/l10n/ddtp.html\";>). </p></footnote>.
<p>Let's insert <tt>Vcs-*</tt> fields documented in
<url name="Developer's Reference, 6.2.5. 'Version Control System location'" id="http://www.debian.org/doc/manuals/developers-reference/best-pkging-practices.html#bpp-vcs";> between line 6 and 7. Let's assume
that the <package>gentoo</package> package is located in Debian Alioth Git
- Service at <tt>git://git.debian.org/git/collab-maint/gentoo.git</tt>.
+ Service at <tt>git://git.debian.org/git/collab-maint/gentoo.git</tt>
+ <footnote><p>The <package>gentoo</package> does not use the Git service.
+ Now is located in <url id="http://sourceforge.net/projects/gentoo/";>.</p></footnote>.
<p>Finally, here is the updated <file>control</file> file:
@@ -1409,9 +1463,17 @@
LGPL-2.1, LGPL-3, GNU FDL-1.2, GNU FDL-1.3, Apache-2.0 or the Artistic license, you can just refer to the
appropriate file in <file>/usr/share/common-licenses/</file> directory that
exists on every Debian system. Otherwise, you must include the complete
- license.
-
- <p>In short, here's how <package>gentoo</package>'s <file>copyright</file> file should look like:
+ license. We must bear in mind that licenses affect <tt>all</tt> files
+ to be included in the package: documentation, source code, images,
+ etc. It may be the case that separate licenses are applied to some files.
+
+ <p>In short, here's how <package>gentoo</package>'s <file>copyright</file> file should look like
+ <footnote><p>The current Debian rules should indicate that
+ the documents cited herein are written in English. If you are
+ unfamiliar with the text of the license, maybe you should read.
+ You'll find the original versions and translations into
+ <url id=\"http://www.gnu.org/licenses/\";>.
+ </p></footnote>:
<example>
1 Format-Specification: http://svn.debian.org/wsvn/dep/web/deps/dep5.mdwn?op=file&rev=135
@@ -1449,7 +1511,8 @@
33 License version 2 can be found in the file
34 `/usr/share/common-licenses/GPL-2'.
</example>
- (I've added the line numbers.)
+ (I've added the line numbers. See the last <package>gentoo</package>'s <file>copyright</file> file
+ into <url id="http://packages.debian.org/changelogs/pool/main/g/gentoo/gentoo_0.19.7-1/gentoo.copyright";>)
<p>Please follow the HOWTO provided by ftpmasters and sent to debian-devel-announce:
<url id="©right-howto;">.
@@ -1798,7 +1861,8 @@
<list>
<item>Install the <package>dkms</package> package in "<tt>Build-Depends</tt>".
<item>Use "<tt>dh --with dkms $@</tt>" instead.
-<item>This correctly handles DKMS usage by the kernel module package.
+<item>This correctly handles DKMS («Dynamic Kernel Module Support»
+is an environment that allows the compilation of kernel modules for Linux) usage by the kernel module package.
</list>
<item>Add support of the <prgn>dh_autotools-dev_updateconfig</prgn> and <prgn>dh_autotools-dev_restoreconfig</prgn> commands.
<list>
@@ -2000,7 +2064,10 @@
<p>Since <package>debhelper</package> V3, <manref name="dh_installdeb" section="1"> will
<em>automatically</em> flag any files under the <file>/etc</file> directory
- as conffiles, so if your program only has conffiles there you do not need to
+ as conffiles
+ <footnote><p>See <url name="7.5 What is a Debian conffile?"
+ id="http://www.debian.org/doc/FAQ/ch-pkg_basics.en.html";>.
+ </p></footnote>, so if your program only has conffiles there you do not need to
specify them in this file. For most package types, the only place there is
(and should be conffiles) is under <file>/etc</file> and so this file doesn't
need to exist.
@@ -2434,7 +2501,7 @@
"<tt>http://sf.net/gentoo</tt>" is downloaded and searched for links of the
form "<tt><a href=...></tt>". The base name (just the part after the
final "<tt>/</tt>") of these linked URLs are matched against Perl regexp (see
- <manref name="perlre" section="1">) pattern "<tt>gentoo-(.+)\.tar\.gz</tt>".
+ <manref name="perlre" section="1">) pattern "<tt>gentoo-(.*)\.tar\.gz</tt>".
Out of matched files, the file with the greatest version number is
downloaded and the <prgn>uupdate</prgn> program is run to create the updated
source tree from them.
@@ -2447,7 +2514,7 @@
The URL redirector service at this <url id="http://qa.debian.org/";> is
designed to offer a stable redirect service to the desired file for the
<file>watch</file> file having
- "<tt>http://sf.net/<var>project</var>/<var>tar-name</var>-(.+)\.tar\.gz</tt>".
+ "<tt>http://sf.net/<var>project</var>/<var>tar-name</var>-(.*)\.tar\.gz</tt>".
This solves issues related to the periodically changing URL there.
<sect id="sourcef"><file>source/format</file> file
@@ -2574,7 +2641,7 @@
<p>Then you issue the following command in the source directory:
<example>
-$ dpkg-buildpackage
+$ dpkg-buildpackage -rfakeroot
</example>
<p>This will do everything to make full binary and source packages for you. It will:
@@ -2589,7 +2656,14 @@
</list>
<p>The only input that will be required of you is your GPG secret pass
- phrase, twice.
+ phrase, twice
+ <footnote><p>For upload the packages to the Debian repository
+ (or to Debian Mentors)
+ must be signed by the developer with a GPG signature.
+ Should generate a GPG key if you have not already.
+ There is much information about this topic: it may be helpful
+ <url id="http://ekaia.org/blog/2009/05/10/creating-new-gpgkey/";>.
+ </p></footnote>.
<p>After all this is done, you will see the following files in the
directory above (<file>~/gentoo</file>):
@@ -2847,7 +2921,14 @@
packages properly for <tt>sid</tt>. In reality, <tt>sid</tt> may be
experiencing issues which makes it not desirable for you to migrate your
whole system. The <package>pbuilder</package> package can help you to cope
- with this kind of situation.
+ with this kind of situation
+ <footnote><p>Typically, new packages or new versions of packages
+ already in the Debian repository, they are compiled for the <tt>sid</tt>
+ version. Once you have passed a test period in this release
+ are transferred to the testing version and finally to the stable.
+ You must set the version used for <package>pbuilder</package>
+ to build the package build environment adding the line DIST=sid
+ into <file>./.pbuilderrc</file> configuration file</p></footnote>.
<p>You may need to update your <tt>stable</tt> packages after their release for
<tt>stable-proposed-updates</tt>, <tt>stable/updates</tt>, etc.
@@ -3057,7 +3138,9 @@
<p>You can compare two <file>diff.gz</file> files with the
<manref name="interdiff" section="1"> command. This is useful for verifying
that no inadvertent changes were made to the source by the maintainer when
- updating packages in the old <tt>1.0</tt> source format.
+ updating packages in the old <tt>1.0</tt>
+ <footnote><p>Packages built with the new <tt>3.0</tt> format
+ don't have <file>diff.gz</file> file.</p></footnote> source format.
<example>
$ interdiff -z <var>old-package</var>.diff.gz <var>new-package</var>.diff.gz
@@ -3106,7 +3189,8 @@
<p>The <tt>$default_host</tt> option determines which of
the upload queues will be used by default. <tt>anonymous-ftp-master</tt> is the primary
- one, but it's possible that you will want to use another one.
+ one, but it's possible that you will want to use another one
+ (see «Uploading a package», in <file>&uploading;</file>).
<p>While connected to the Internet, you can upload your package by the following:
Reply to: