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 -- To UNSUBSCRIBE, email to [email protected] with a subject of "unsubscribe". Trouble? Contact [email protected] Archive: http://lists.debian.org/[email protected]
