Re: Updated maint-guide contents, question on style
Chapter 9.
I replaced the hypothetical bugreport #54321 (which happened in
January 2000) with #654321 (coming soon). If you're cunning you could
arrange for that to be a bugreport complaining that #654321 is
fictional, and then close it as self-fixing. Alternatively, #543210
was reported in 2009.
Footnote 80 mentions cdbs v0.4.74 criticising Lenny's dh_make; I don't
see any such comments in v0.4.93, so maybe this footnote's obsolete.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
--- maint-guide.en.dbk.pristine 2011-04-17 14:35:41.052916002 +0100
+++ maint-guide.en.dbk 2011-04-28 11:59:35.205258983 +0100
@@ -4578,13 +4578,13 @@
</chapter>
<chapter id="update"><title>Updating the package</title>
<para>
-Once you release a package, you need to update it soon.
+After you release a package, you will soon need to update it.
</para>
<section id="newrevision"><title>New Debian revision</title>
<para>
Let's say that a bug report was filed against your package as
-<literal>#54321</literal>, and it describes a problem that you can solve. To
-create a new Debian revision of the package, you need to:
+<literal>#654321</literal>, and it describes a problem that you can solve.
+Here's what you need to do to create a new Debian revision of the package.
</para>
<itemizedlist>
<listitem>
@@ -4595,13 +4595,13 @@
<listitem>
<para>
<literal>dquilt new <replaceable>bugname.patch</replaceable></literal> to set
-patch name;
+the patch name;
</para>
</listitem>
<listitem>
<para>
<literal>dquilt add <replaceable>buggy-file</replaceable></literal> to declare
-file to be modified;
+the file to be modified;
</para>
</listitem>
<listitem>
@@ -4611,7 +4611,7 @@
</listitem>
<listitem>
<para>
-<literal>dquilt refresh</literal> to record to
+<literal>dquilt refresh</literal> to record it to
<filename><replaceable>bugname.patch</replaceable></filename>;
</para>
</listitem>
@@ -4630,7 +4630,7 @@
<listitem>
<para>
<literal>dquilt pop <replaceable>foo.patch</replaceable></literal> to recall
-existing <filename><replaceable>foo.patch</replaceable></filename>;
+the existing <filename><replaceable>foo.patch</replaceable></filename>;
</para>
</listitem>
<listitem>
@@ -4672,9 +4672,9 @@
<listitem>
<para>
Include a short description of the bug and the solution in the changelog entry,
-followed by <literal>Closes: #54321</literal>. That way, the bug report will
+followed by <literal>Closes: #654321</literal>. That way, the bug report will
be <emphasis>automagically</emphasis> closed by the archive maintenance
-software the moment your package gets accepted in the Debian archive.
+software the moment your package gets accepted into the Debian archive.
</para>
</listitem>
<listitem>
@@ -4694,17 +4694,17 @@
</section>
<section id="inspectnewupstream"><title>Inspection of the new upstream release</title>
<para>
-When preparing packages of the new upstream release for the Debian archive, you
+When preparing packages of the a upstream release for the Debian archive, you
must check the new upstream release, first.
</para>
<para>
-You start this by reading the upstream <filename>changelog</filename>,
-<filename>NEWS</filename>, and whatever other documentations they may have
+Start by reading the upstream <filename>changelog</filename>,
+<filename>NEWS</filename>, and whatever other documentation they may have
released with the new version.
</para>
<para>
-You then inspect changes between the old and new upstream sources as follow to
-watch out for anything suspicious.
+You can then inspect changes between the old and new upstream sources as follows,
+watching out for anything suspicious.
</para>
<screen>
$ diff -urN <replaceable>foo</replaceable>-<replaceable>oldversion</replaceable> <replaceable>foo</replaceable>-<replaceable>newversion</replaceable>
@@ -4716,7 +4716,7 @@
<filename>config.sub</filename>, <filename>configure</filename>,
<filename>depcomp</filename>, <filename>install-sh</filename>,
<filename>ltmain.sh</filename>, and <filename>Makefile.in</filename> may be
-ignored. You may erase them before running <command>diff</command> to the
+ignored. You may delete them before running <command>diff</command> on the
source for inspection.
</para>
</section>
@@ -4732,12 +4732,12 @@
old <literal>1.0</literal> format, this can be done by running <literal>zcat
/<replaceable>path</replaceable>/<replaceable>to</replaceable>/<replaceable>foo</replaceable>_<replaceable>oldversion</replaceable>.diff.gz|patch
-p1</literal> in the new extracted source, instead. </para> </footnote> Of
-course, you need to do few obvious chores.
+course, you need to do some obvious chores.
</para>
<itemizedlist>
<listitem>
<para>
-Create a copy of upstream source as the
+Create a copy of the upstream source as the
<filename>foo_<replaceable>newversion</replaceable>.tar.gz</filename> file.
</para>
</listitem>
@@ -4780,7 +4780,7 @@
<itemizedlist>
<listitem>
<para>
-If a patch you applied to the source was integrated to the upstream source,
+If a patch you applied to the source was integrated into the upstream source,
</para>
<itemizedlist>
<listitem>
@@ -4805,7 +4805,7 @@
<listitem>
<para>
Edit the <filename><replaceable>baz</replaceable></filename> file manually to
-realize intended effect of
+bring about the intended effect of
<filename><replaceable>baz</replaceable>.rej</filename>.
</para>
</listitem>
@@ -4818,7 +4818,7 @@
</listitem>
<listitem>
<para>
-Continue back to <literal>while dquilt push; do dquilt refresh; done</literal>.
+Continue as usual with <literal>while dquilt push; do dquilt refresh; done</literal>.
</para>
</listitem>
</itemizedlist>
@@ -4866,23 +4866,24 @@
<section id="packagestyle"><title>Updating the packaging style</title>
<para>
Updating the package style is not a required activity for the update of a
-package. But, you can use the full capability of the modern <systemitem role="package">debhelper</systemitem> system and the <literal>3.0</literal>
-source format by doing this. <footnote><para> If your sponsor or other
-maintainers object to updating the existing packaging style, it is not worth
-bothering nor arguing. There are more important things to do. </para>
+package. However, doing so lets you use the full capabilities of the modern
+<systemitem role="package">debhelper</systemitem> system and the <literal>3.0</literal>
+source format. <footnote><para> If your sponsor or other
+maintainers object to updating the existing packaging style, don't bother
+arguing. There are more important things to do. </para>
</footnote>
</para>
<itemizedlist>
<listitem>
<para>
-If you need to add erased template files for any reason, you may run
+If you need to recreate deleted template files for any reason, you can run
<command>dh_make</command> again in the same Debian package source tree with
-<literal>--addmissing</literal> option. Then edit them properly.
+the <literal>--addmissing</literal> option. Then edit them appropriately.
</para>
</listitem>
<listitem>
<para>
-If the package has not updated to use the <systemitem role="package">debhelper</systemitem> V7 <command>dh</command> syntax for the
+If the package has not been updated to use the <systemitem role="package">debhelper</systemitem> v7 <command>dh</command> syntax for the
<filename>debian/rules</filename> file, update it to use <command>dh</command>.
Update the <filename>debian/control</filename> file accordingly.
</para>
@@ -4898,7 +4899,7 @@
<systemitem role="package">cdbs</systemitem> (0.4.74) package, there are some
negative descriptions of the <filename>rules</filename> file created by the
<command>dh_make</command> command for the non-<systemitem role="package">cdbs</systemitem> choices. Do not worry about it. It applies
-only for <literal>lenny</literal> which created explicit targets with long list
+only for <literal>lenny</literal> which created explicit targets with long lists
of <command>dh_*</command> commands. </para> </footnote>
</para>
</listitem>
@@ -4908,8 +4909,8 @@
<filename><replaceable>foo</replaceable>.diff.gz</filename> file, you can
update it to the newer <literal>3.0 (native)</literal> source format by
creating <filename>debian/source/format</filename> with <literal>3.0
-(native)</literal>. The rest of <filename>debian/*</filename> files can be
-just copied.
+(native)</literal>. The rest of the <filename>debian/*</filename> files can just be
+copied.
</para>
</listitem>
<listitem>
@@ -4918,17 +4919,17 @@
<filename><replaceable>foo</replaceable>.diff.gz</filename> file, you can
update it to the newer <literal>3.0 (quilt)</literal> source format by creating
<filename>debian/source/format</filename> with <literal>3.0 (quilt)</literal>.
-The rest of <filename>debian/*</filename> files can be just copied. Import the
-<filename>big.diff</filename> file generated by the <literal>filterdiff -z -x
+The rest of the <filename>debian/*</filename> files can just be copied. Import the
+<filename>big.diff</filename> file generated by the command <literal>filterdiff -z -x
'*/debian/*' <replaceable>foo</replaceable>.diff.gz > big.diff</literal>
-command to your <command>quilt</command> system, if needed. <footnote><para>
-You may split <filename>big.diff</filename> into many small incremental patches
+to your <command>quilt</command> system, if needed. <footnote><para>
+You can split <filename>big.diff</filename> into many small incremental patches
using the <command>splitdiff</command> command. </para> </footnote>
</para>
</listitem>
<listitem>
<para>
-If it was packaged with another patch system such as <systemitem role="package">dpatch</systemitem>, <systemitem role="package">dbs</systemitem>, or <systemitem role="package">cdbs</systemitem> with <literal>-p0</literal>,
+If it was packaged using another patch system such as <systemitem role="package">dpatch</systemitem>, <systemitem role="package">dbs</systemitem>, or <systemitem role="package">cdbs</systemitem> with <literal>-p0</literal>,
<literal>-p1</literal>, or <literal>-p2</literal>, convert it to the
<systemitem role="package">quilt</systemitem> command using
<filename>deb3</filename> at <ulink url="&deb3;"/>.
@@ -4939,13 +4940,13 @@
If it was packaged with the <command>dh</command> command with the
<literal>--with quilt</literal> option or with the
<command>dh_quilt_patch</command> and <command>dh_quilt_unpatch</command>
-commands, remove such things and make it use the newer <literal>3.0
+commands, remove these and make it use the newer <literal>3.0
(native)</literal> source format.
</para>
</listitem>
</itemizedlist>
<para>
-You need to do other tasks described in <xref linkend="newupstream"/>, too.
+You need to do the other tasks described in <xref linkend="newupstream"/>, too.
</para>
</section>
<section id="reminders"><title>Reminders for updating packages</title>
@@ -4956,7 +4957,7 @@
<listitem>
<para>
Preserve old <filename>changelog</filename> entries (sounds obvious, but there
-have been incidents to type <literal>dch</literal> when you should have typed
+have been cases of people typing <literal>dch</literal> when they should have typed
<literal>dch -i</literal>.)
</para>
</listitem>
@@ -4977,15 +4978,15 @@
</listitem>
<listitem>
<para>
-Check to see <ulink url="&bts;">Debian Bug Tracking
-System (BTS)</ulink> if someone have provided patches to bugs that are
-currently open in it.
+Check the <ulink url="&bts;">Debian Bug Tracking
+System (BTS)</ulink> to see if someone has provided patches to bugs that are
+currently open.
</para>
</listitem>
<listitem>
<para>
Check the contents of the <filename>.changes</filename> file to make sure you
-are uploading to the correct distribution, the proper bugs closures are listed
+are uploading to the correct distribution, the proper bug closures are listed
in the <literal>Closes</literal> field, the <literal>Maintainer</literal> and
<literal>Changed-By</literal> fields match, the file is GPG-signed, etc.
</para>
Reply to: