Re: Bug#618352: maint-guide: English source update suggestions
Hi,
On Tue, Mar 15, 2011 at 10:07:11PM +0900, Osamu Aoki wrote:
> Hi,
>
> With aftermath of the earthquake, I am a bit tired with crowded commuter
> train ....
Things are getting a bit normal in Tokyo.
Anyway, I have converted this to DocBook XML. I have made subversion
commit and source is building in good shape.
Please hold off updating translation yet. But review new English
contents at http://www.debian.org/doc/manuals/maint-guide/index.en.html
I will perform entity conversion of all the URL soon for all languages
soon. Then it will be ready for translation updates.
> On Mon, Mar 14, 2011 at 07:34:21PM +0100, Innocent De Marchi wrote:
I am including your suggestions etc. soon. There were some change of
minds and restructuring. Since this is for wheezy, I am more inclusive
than before. I am afraid creating so many links to Policy may be
maintenance night mare, though.
| <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.
This was intentional choice after serious discussion with uupdate upstream etc.
| @@ -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>
I expect people to get enough idea by this word and PEOPLE are expected to read manpage.
| @@ -2574,7 +2652,7 @@
| <p>Then you issue the following command in the source directory:
|
| <example>
| -$ dpkg-buildpackage
| +$ dpkg-buildpackage -rfakeroot
| </example>
manpage say "fakeroot will be used by default".
| <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>.
Ana's description was good but not good stable URL for basic information.
I do not want t dwell on Debian Mentors service too much here either.
http://wiki.debian.org/Keysigning seems good one.
http://mentors.debian.net/ is mentioned elsewhere.
| <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.
You mean "Debian revision". Considering expected change to source only etc, I
am conservative describing here.
See policy stating "It is conventional to restart the debian_revision at 1 each
time the upstream_version is increased."
If revision is 0 or 1, you do not need to have -sd. This is what we need here.
I rephrased the whole paragraph in XML source.
| <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>.
OK.
| <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>.
I do not do this and I do not want too much information overload.
| <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>..
|
??? this is default.
| <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)
I do not want this.
| <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.
Let's make one section for tar --diff text ... for debian.tar.gz as example.
| <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>)..
Hmm.... &uploading; ... maybe URL is better and consistent.
| <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>).
OK.
<para>
Describe concisely the changes <emphasis>in the new upstream release</emphasis>
that fix reported bugs and close those bugs by adding "<literal>Closes: #<replaceable>bug_number</replaceable></literal>".
</para>
| <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>).
OK.
| </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\";>).
No need. People should use the latest one at the last.
I like to keep it simple.
| <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
|
Please see new files in subversion soon.
Osamu
Reply to: