maint-guide: English source update suggestions
Package: maint-guide
Version: 1.2.25
Severity: wishlist
Hi,
On Sun, Mar 13, 2011 at 06:48:41PM +0100, Innocent De Marchi wrote:
> Hi Osamu,
>
> I saw your post about the migration of maint-guide to DocBook
> XML. I am available for translations into Spanish and Catalan.
> Tell me if you have something to do with these translations.
>
> >If you have problem in English text, now is the good time to ask
> >changes.
>
> I sent you a file with suggested changes to the original version.
> The diff file changes (in English sgml version) is attached to the email.
Sorry, I lost track of this .... I kind of remember this ...
Let me file as wishlist bug so i will not loose this.
| --- maint-guide.en.sgml 2011-01-30 17:25:45.000000000 +0100
| +++ maint-guide.en-original_contributions.sgml 2011-01-30 18:57:37.000000000 +0100
| @@ -96,8 +96,9 @@
| <p>Newer versions of this document should always be available online at
| <url name="http://www.debian.org/doc/maint-guide/"; id="http://www.debian.org/doc/maint-guide/";>
| and in the <package/maint-guide/ package.
| - <!-- Translation in <this language> is also available in the
| - <package/maint-guide-xy/ package. -->
| + The translations (perhaps without upgrading to the latest version of the
| + original in English) are distributed in the package <package>maint-guide-xx</package>
| + (where xx is the language code).
This one will be dealt a bit differently for translation. You will see new
easier translation specific addendum method in my updated build script.
| <sect id="needprogs">Programs you need for development
|
| @@ -109,7 +110,8 @@
| <p>The following packages come with the standard Debian installation,
| so you probably have them already (along with any additional packages
| they depend on).
| - Still, you should check it with "<tt>aptitude show <var>package</var></tt>".
| + Still, you should check it with "<tt>aptitude show <var>package</var></tt>"
| + or with <tt>dpkg -s <var>package</var></tt>.
| <p>
| The most important package to install on your development system is the
Good idea.
| @@ -268,7 +270,10 @@
|
| <item><strong>source package</strong>: A source package is a set of files
| which contain code and data which you can compile and process into execution
| - programs and formatted documents. It usually comes as a combination of
| + programs and formatted documents.
| + <footnote><p>This document is the result of processing a <file>.po</file> file format
| + to get a <file>pdf</file> file or a set of files in HTML format.</p></footnote>.
| + It usually comes as a combination of
| <file>*.orig.tar.gz</file>, <file>*.debian.tar.gz</file> (or
| <file>*.diff.gz</file>), and <file>*.dsc</file>. Some other archive and
| compression methods may be used, too.
If I were to add this, "processing a <file>maint-guide.en.dbk</file> file and
<file>maint-guide.??.po</file>" should be the words to describe source files
for the translation. I see your thought to address specifics for this package.
But is this really essential to mention this?
| @@ -287,7 +292,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.
Hmmm... you really want to explain how this doc package is packaged. But this
document is more about execution program package. Putting too much information
tends to loose focus and confused audience.
| @@ -310,7 +315,7 @@
|
| </list>
|
| - <p>There are several version names used around Debian.
| + <p>There are several version names (see <ref id="namever">) used around Debian.
|
| <list>
| <item><strong>upstream source version</strong>: The upstream source version is referred as <tt><var>version</var></tt>.
Link to <ref id="namever"> is a good idea. But link to
http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version
is something needed too. How to get them all linked nicely.. let me
think...
| @@ -334,7 +339,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
<!ENTITY newmaint "http://www.debian.org/devel/join/newmaint";>
<!ENTITY mentors-faq "http://people.debian.org/~mpalmer/debian-mentors_FAQ.html";>
--> This needs to be: http://wiki.debian.org/DebianMentorsFaq
| @@ -350,7 +356,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 to 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
<!ENTITY nm-home "http://nm.debian.org/";>
&newmaint; is part of &nm-home;. &mentors-faq; is extensive source of info. I
do not want to duplicate in this way. It is good idea to mention &mentors-faq;
though. Let me think.
I do not understand your addition of <footnote>...</footnote>. I think you try
to say something along:
|| See all the information at <url id="&nm-home;"> and and
|| <url id="&mentors-faq;"> to gain upload access to the Debian archive as DD or
|| DM.
| @@ -358,12 +366,14 @@
|
| <p>If you still have questions about packaging that you couldn't find answers to
| in the available documentation and web resources, you can ask them on the Debian Mentors' mailing list
| - at <url id="http://lists.debian.org/debian-mentors/"; name="debian-mentors@lists.debian.org">. The more experienced Debian
| + at <url id="http://lists.debian.org/debian-mentors/"; name="debian-mentors@lists.debian.org">
| + and the IRC #debian-mentors (may have a IRC of mentors in your language).
| + The more experienced Debian
| 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.
| + information about this mailing list and the IRC channel #debian-mentors.
|
| <p>When you receive
| a bug report (yes, actual bug reports!), you will know that it is time for you
I got your point on IRC. But inclusion of "...mentors in your language" can be
done a bit differently. I will think about it.
| @@ -389,7 +399,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
|
I see your point. But following "2.1 Choose your program" list this and more.
Isn't this too much duplication?
| @@ -406,8 +417,9 @@
| <url name="Debian QA Group" id="http://qa.debian.org/";>, you may
| be able to pick it up if it's still available (check the ownership status
| 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
| + You may also adopt a package for which the corresponding maintainer (or a DD) has filed
| a "Request for Adoption" (<strong>RFA</strong>).
This could be DM. So let's leave this without "(or a DD)" as was.
| + See <url id="http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=594398";> for an example.
Can you elaborate why you picked this example from other possible candidates?
| <p>Several different views of orphaned or RFA'ed packages are available at:
| <list>
| @@ -427,12 +439,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";>)
popcon gives us popularity but this interface is not the best entry to find
actively used packages.
| <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>.
You insist to put this dspite I have link to "5.11.6. NMUs vs QA upload" in
developers-reference.
| </list>
|
| - <p>If you are able to adopt the package, get the sources (with something
| + <p>If you are able to adopt the package, get the sources
| + <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
I see your point to explain more around here. Quite frankly, this maint-guide
is not primary place to describe NMU nor WNPP nor DM process. I think we
should not duplicate too much contents. That will lead to unmaintainable
document. This should only give pointer to such info and this should focus on
what it is good .... technical aspect of simple packaging. Let me use this as
reference and trim them down a bit.
| 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
| @@ -526,7 +553,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>
Thanks for finding this out. Since 0.19.8 may not be "Current", we may want to use "More recent".
Then we do not need to update this version number often.
| <p>Create a subdirectory under your home directory named <file>debian</file> or <file>deb</file>
| @@ -555,7 +582,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
How about ...:
<p>The build process of programs varies from program to program. Simpler
programs come with a <file>Makefile</file> file in them. Many modern programs
come with a script <file>configure</file> which creates a <file>Makefile</file>
file customized for your system upon its execution. These programs can be
build simply with "<tt>make</tt>" using the <file>Makefile</file> file.
<p>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>".
| @@ -759,7 +790,10 @@
| <tt>--addmissing</tt> option again in a Debian package
| source tree.
|
| - <p>Updating an existing package may get complicated since it may be using
| + <p>Please note that you should run <prgn>dh_make</prgn> only once,
| + and not behave correctly if you do it again in the same directory
| + with the <file>debian</file> directory already generated.
| + Updating an existing package may get complicated since it may be using
| older techniques. Please stick with fresh packaging cases for now to learn
| basics. I will come back to explain it later in <ref id="update">.
I intentinally removed this warning... We have -a, --addmissing option now.
| @@ -829,7 +863,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 <tt>-</tt> and then the new lines are preceded by a <tt>+</tt>. 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>..
I like dep3 reference but explanation of patch seems exessive.
| <example>
| $ quilt refresh
| @@ -863,7 +906,8 @@
| <list>
| <item>The <file>Makefile</file> file follows the GNU conventions to
| support <tt>$(DESTDIR)</tt> variable
| - (<file>/usr/share/doc/gnu-standards/standards.html#Makefile-Conventions</file>).
| + (<file>/usr/share/doc/gnu-standards/standards.html#Makefile-Conventions</file>
| + and <file>http://www.gnu.org/prep/standards/html_node/DESTDIR.html#DESTDIR</file>).
Thanks.
| <item>The source follows the Filesystem Hierarchy Standard (FHS).
| </list>
| <p>Programs that use GNU <prgn>autoconf</prgn> <em>automatically</em> follow
| @@ -901,6 +945,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.
Let me think what to do. I intentinally left this technical aspect out since
readers are expected to read dpkg document etc.
| <p>Here's the relevant part of <package>gentoo</package>'s
| <file>Makefile</file> file
| @@ -955,10 +1006,13 @@
| $ grep -nr -e 'usr/local/lib' --include='*.[c|h]' .
| </example>
|
| - <p><prgn>grep</prgn> will run recursively through the source tree and tell
| - you the filename and the line number for all matches.
| + <p><prgn>grep</prgn> will run recursively through the source tree
| + searching files with <tt>.c</tt> and <tt>.h</tt> extension and show
| + you the filename and the line number when it finds a match with the
| + chain <file>usr/local/lib</file>.
With s/chain/string/, this is good suggestion for novice. Do we need to be so
wordy for "grep", that is somehing I wonder. Why not read manpage if the
reader is new maint candidate...
| <p>Edit those files and in those lines replace <tt>usr/local/lib</tt> with <tt>usr/lib</tt>.
| + Can be done automatically with this order:
How aboout:
This can be done automatically as follows:
(We Japanese and Spanish people tend to drop obvious subject words.... but
Anglophone does not like it.)
| <example>
| $ vim '+argdo %s/usr\/local\/lib/usr\/lib/gce|update' +q \
| $(find . -type f -name '*.[c|h]')
| @@ -970,7 +1024,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
This seems to be a valid fix.
| @@ -1079,7 +1133,7 @@
| other package management tools will use to manage the package. It is defined by the
| <url name="Debian Policy Manual, 5 'Control files and their fields'" id="http://www.debian.org/doc/debian-policy/ch-controlfields.html";>.
|
| - <p>Here is the control file <prgn>dh_make</prgn> created for us:
| + <p>Here is the <file>control</file> file <prgn>dh_make</prgn> created for us:
|
| <example>
| 1 Source: gentoo
This seems to be a valid fix.
| @@ -1119,7 +1173,8 @@
| for the guidance.
|
| <p>Let's change it then to x11. (A <tt>main/</tt> prefix is implied so we can
| - omit it.)
| + omit it.). See <url id=\"http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections\";
| + name=\"Debian Policy Manual, 2.4 'Sections'\">.
|
OK. URL lining is something we need to be careful though.
(It is getting late... I need to get to bed....)
==== Following are not checked well ====
| <p>Line 3 describes how important it is that the user installs this package.
| See the <url name="Debian Policy Manual, 2.5 'Priorities'" id="http://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities";>
| @@ -1232,13 +1287,15 @@
| 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>.
| + 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>
| @@ -1329,7 +1386,8 @@
| packages they are in, such as <package>libc6</package> or
| <package>xlib6g</package>, after your package has been built and installed
| into the temporary directory. This list of shared library dependencies is
| - used for <tt>${shlibs:Depends}</tt>.
| + used for <manref section=\"1\" name=\"dh_gencontrol\"> that will replace the
| + <tt>${shlibs:Depends}</tt> variable for the dependencies list.
|
| <p>The package list generated by the <manref name="dh_perl" section="1"> is
| used for <tt>${perl:Depends}</tt>.
| @@ -1351,12 +1409,17 @@
| 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
| + (see <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 +1472,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>::
???
I agree that we have to have a bit more clear requirement for "all source" but
this GNU reference does not fit well here.
|
| <example>
| 1 Format-Specification: http://svn.debian.org/wsvn/dep/web/deps/dep5.mdwn?op=file&rev=135
| @@ -1798,7 +1869,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.
Should we dwell on such detail here. This is a text used by dh_dkms(1) manpage.
Novice are not going to use this and whoever needs this should read full manpage.
| </list>
| <item>Add support of the <prgn>dh_autotools-dev_updateconfig</prgn> and <prgn>dh_autotools-dev_restoreconfig</prgn> commands.
| <list>
| @@ -2000,7 +2072,9 @@
|
| <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";>.
??? http://www.debian.org/doc/FAQ/ch-pkg_basics.en.html#s-conffile
FAQ is not good place as URL reference from this doc. Policy is better but its
description is useless:
http://www.debian.org/doc/debian-policy/ap-pkg-controlfields.html#s-pkg-f-Conffiles
"man dh_installdeb" tells most. Let me thisk.
| + </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.
| @@ -2061,7 +2135,7 @@
|
| <p>It is best to first try to run the installation first and only use
| this if you run into trouble. There is no preceding slash on the
| - directory names.
| + directory names (listed in the file <file>dirs</file>)..
|
| <sect id="doc-base"><file><var>package</var>.doc-base</file> file
|
| @@ -2422,7 +2496,9 @@
| got the source from. This is also used by
| <url id="http://wiki.debian.org/DEHS"; name="Debian External Health Status (DEHS)">.
|
| - <p>Here's what I put in it:
| + <p>Here's what I put in it <footnote><p>connect to internet and try to
| + run the program <prgn>uscan</prgn> in the directory where you built
| + the package. Check the man page to learn more.</p></footnote>):
|
| <example>
| # watch control file for uscan
| @@ -2434,7 +2510,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.
| @@ -2457,7 +2533,9 @@
| (check <manref name="dpkg-source" section="1"> for an exhaustive list). After
| <tt>squeeze</tt>, it should say either:
| <list>
| - <item><tt>3.0 (native)</tt> for Debian native packages or
| + <item><tt>3.0 (native)</tt> for Debian native packages
| + <footnote><p>A package is Debian native package if is only distributed in Debian:
| + it is a specific package of this distribution.</p></footnote> or
| <item><tt>3.0 (quilt)</tt> for everything else.
| </list>
|
| @@ -2574,7 +2652,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 +2667,11 @@
| </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>):
| @@ -2711,7 +2793,10 @@
| not the first one for the given upstream version, you must provide
| <prgn>dpkg-buildpackage</prgn> command with the "<tt>-sa</tt>" option.
| On the other hand, the "<tt>-sd</tt>" option will force to exclude the
| -original <file>orig.tar.gz</file> source.
| +original <file>orig.tar.gz</file> source. The original sources file
| +are included in the package only to upload it to the Debian archive
| +when the build system detects that it is a new version.
| +For this reason, the firts Debian version number must be 0 or 1.
|
| <sect id="debuild"><prgn>debuild</prgn> command
|
| @@ -2760,7 +2845,7 @@
| This ensures a clean build from the source under the <tt>sid</tt> auto-builder
| for different architectures and avoids the severity serious FTBFS (Fails To
| Build From Source) bug which is always in the RC (release critical) category.
| -See <url id="&buildd-home;"> for more on the Debian package auto-builder.
| +See <url id="&buildd-home;"> for more on the Debian package <package>auto-builder</package>.
|
| <p>Let's customize the <package>pbuilder</package> package by the following.
| <list>
| @@ -2803,7 +2888,11 @@
|
| <p>
| The newly built packages will be located in
| -<file>/var/cache/pbuilder/result/</file> with non-root ownership.
| +<file>/var/cache/pbuilder/result/</file> with non-root ownership
| +<footnote><p>If you add the following line BUILDRESULT=\"$HOME/pbuilder\"
| +into the <file>pbuilder</file> configuration file (<file>./.pbuilderrc</file>), the package files
| +are saved in the <file>$HOME/pbuilder\</file> directory (you can
| +put anything in place <file>/pbuilder\</file> directory).</p></footnote>.
|
| <p>If you already have the updated source tree without generating the matching
| source packages, issue the following commands in the source directory where the
| @@ -2847,7 +2936,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.
| @@ -2925,7 +3021,7 @@
| <p>Testing on machine other than your own is also good idea. You must watch
| closely for any warnings or errors for all the test described here.
|
| - <sect id="pinstall">Verifying package for install
| + <sect id="pinstall">Verifying package for install (<prgn>debi</prgn> command)
|
| <p>You must test your package if it installs without problem.
| The <manref name="debi" section="1"> command helps you to test to install all
| @@ -3057,7 +3153,8 @@
| <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 +3203,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:
|
| @@ -3261,9 +3359,9 @@
| <list>
| <item>Add an entry with "New upstream release".
| <item>Describe concisely the changes <em>in the new upstream release</em>
| - that fix reported bugs and close those bugs.
| + that fix reported bugs and close those bugs (adding <tt>(Closes: #bug_number)</tt>).
| <item>Describe concisely the changes <em>to the new upstream release</em> by
| - the maintainer that fix reported bugs and close those bugs.
| + the maintainer that fix reported bugs and close those bugs (adding <tt>(Closes: #bug_number)</tt>).
| </list>
| <item>"<tt>while quilt push; do quilt refresh; done</tt>" to apply all patches while removing <em>fuzz</em>.
| </list>
| @@ -3373,7 +3471,7 @@
| <package>dpatch</package>, <package>dbs</package>, or <package>cdbs</package>
| with <tt>-p0</tt>, <tt>-p1</tt>, or <tt>-p2</tt>, convert it to the
| <package>quilt</package> command using <file>deb3</file> at
| - <url id="http://bugs.debian.org/581186";>.
| + <url id="http://bugs.debian.org/581186";> (available at <url id=\"http://bugs.debian.org/cgi-bin/bugreport.cgi?msg=5;filename=deb3;att=1;bug=581186\";>).
|
| <item>If it was packaged with the <prgn>dh</prgn> command with the
| "<tt>--with quilt</tt>" option or with the <prgn>dh_quilt_patch</prgn> and
|
Reply to: