[PATCH v2] upgrading-checklist in present tense?
Russ Allbery wrote:
> Looking back at older entries, the ones I wrote for previous releases are
> also in present tense. Could we standardize in that direction instead?
I can understand the temptation. I might be the only one that is
tempted to read the changes as commands directed to the packager (like
See this debian-devel-announce message for the list of new sections
and rules for how to categorize packages.
or
Clarify Standards-Version: you don't need to rebuild your
packages just to change the Standards-Version!
or
Use logrotate to rotate log files
).
Anyway, here's an alternate (hopefully smaller) patch, taking
advantage of some of the verbs (like "clarify") applying better to
what the section does than to what Russ did. It still puts changes in
the past tense.
upgrading-checklist.sgml | 62 +++++++++++++++++++++++----------------------
1 files changed, 32 insertions(+), 30 deletions(-)
diff --git a/upgrading-checklist.sgml b/upgrading-checklist.sgml
index e603852..ab2d72b 100644
--- a/upgrading-checklist.sgml
+++ b/upgrading-checklist.sgml
@@ -46,29 +46,31 @@ Unreleased.
intended.
</item>
<tag>3.3</tag>
- <item>Clarify the duties of a maintainer, require that the maintainer
- address accept mail from Debian role accounts and the BTS, and require
- at least one human with their personal email address
+ <item>Clarifies the duties of a maintainer. The maintainer address
+ is reqired to accept mail from Debian role accounts and the BTS, and
+ at least one human with their personal email address is required
in <tt>Uploaders</tt> if the maintainer is a shared email address.
</item>
<tag>5.6.25</tag>
- <item>Document the <tt>DM-Upload-Allowed</tt> field.
+ <item>Documents the <tt>DM-Upload-Allowed</tt> field introduced by GR
+ in 2007.
</item>
<tag>6.5</tag>
- <item>Document the system state maintainer scripts can rely upon during
+ <item>Documents the system state maintainer scripts can rely upon during
each possible invocation. In several less-common cases, this is
stricter than Policy had previously documented. Packages with complex
maintainer scripts should be reviewed in light of this new
documentation.
</item>
<tag>7.2</tag>
- <item>Better document the impact on system state when maintainer scripts
- that are part of a circular dependency are run. Circular dependencies
- are now a should not.
+ <item>Packages can rely on their dependencies being unpacked at
+ configure time, even if involved in a circular dependency.
+ Dependency loops involving a Pre-Depends will cause installation
+ to be aborted. Avoidable circular dependencies are a should not.
</item>
<tag>7.2</tag>
- <item>Document the system state when <prgn>postinst</prgn>
- and <prgn>prerm</prgn> scripts are run, and better document the special
+ <item>Documents the system state when <prgn>postinst</prgn>
+ and <prgn>prerm</prgn> scripts are run, and better documents the special
case of dependency state for <prgn>postrm</prgn>
scripts. <prgn>postrm</prgn> scripts are required to gracefully skip
actions if their dependencies are not available.
@@ -125,7 +127,7 @@ Released July, 2010.
<tag>8.1</tag>
<item>The SONAME of a library should change whenever the ABI of the
library changes in a way that isn't backward-compatible. It should not
- change if the library ABI changes are backward-compatible. Discourage
+ change if the library ABI changes are backward-compatible. Discourages
bundling shared libraries together in one package.
</item>
<tag>8.4</tag>
@@ -151,8 +153,8 @@ Released July, 2010.
</item>
<tag>10.2</tag>
<item>Libraries no longer need to be built with <tt>-D_REENTRANT</tt>,
- which was an obsolete LinuxThreads requirement. Instead, say explicitly
- that libraries should be built with threading support and to be
+ which was an obsolete LinuxThreads requirement. Instead, policy says
+ explicitly that libraries should be built with threading support and to be
thread-safe if the library supports this.
</item>
<tag>10.4</tag>
@@ -163,7 +165,7 @@ Released July, 2010.
with <prgn>trap</prgn>.
</item>
<tag>10.8</tag>
- <item>Recommend <file>/etc/logrotate.d/<var>package</var></file> for
+ <item>Recommends <file>/etc/logrotate.d/<var>package</var></file> for
logrotate rules.
</item>
<tag>10.9</tag>
@@ -203,7 +205,7 @@ Released June, 2010.
particular field name.
</item>
<tag>5.4, 5.5, 5.6.24</tag>
- <item>Document and recommend the <tt>Checksums-Sha1</tt>
+ <item>Documents and recommends the <tt>Checksums-Sha1</tt>
and <tt>Checksums-Sha256</tt> fields in <file>*.dsc</file>
and <file>*.changes</file> files.
</item>
@@ -269,7 +271,7 @@ Released June, 2010.
common-licenses for the time being.
</item>
<tag>debconf</tag>
- <item>Add <tt>SETTITLE</tt> (which has been supported for some time).
+ <item>Added <tt>SETTITLE</tt> (which has been supported for some time).
Like <tt>TITLE</tt> but takes a template instead of a string to allow
translation.
</item>
@@ -299,7 +301,7 @@ Release Jan 2010.
<file>/usr/lib/triplet</file> directories.
</item>
<tag>10.6</tag>
- <item>Explicitly state that packages may not contain named pipes and
+ <item>Explicitly states that packages may not contain named pipes and
should instead create them in postinst and remove them in prerm or postrm.
</item>
<tag>9.1.1</tag>
@@ -314,12 +316,12 @@ Released Aug 2009.
</p><p><taglist>
<tag>4.9</tag>
- <item>Add DEB_*_ARCH_CPU and DEB_*_ARCH_OS variables and
- recommend them over GNU-style variables for that information.
+ <item>Added DEB_*_ARCH_CPU and DEB_*_ARCH_OS variables and
+ they are recommended over GNU-style variables for that information.
</item>
<tag>5.6.8</tag>
<item>Source package Architecture fields may contain <em/all/ in
- combination with other architectures. Clarify when <em/all/ and <em/any/
+ combination with other architectures. Clarified when <em/all/ and <em/any/
may be used in different versions of the field.
</item>
<tag>5.6.14</tag>
@@ -330,18 +332,18 @@ Released Aug 2009.
<item>The Binary field may span multiple lines.
</item>
<tag>10.2</tag>
- <item>Remove the permission for shared library packages to
+ <item>Removed the permission for shared library packages to
install libraries in a non-standard location and modify <file/ld.so.conf/.
Packages should either be installed in a standard library directory
or packages using them should be built with RPATH.
</item>
<tag>11.8.7</tag>
- <item>Clarify installation directories for X programs and
- remove the requirement to pre-depend on x11-common before installing
+ <item>Clarified installation directories for X programs and
+ removed the requirement to pre-depend on x11-common before installing
into <file>/usr/include/X11</file> and <file>/usr/lib/X11</file>.
</item>
<tag>12.1</tag>
- <item>Remove the requirement that all characters in a manual
+ <item>Removed the requirement that all characters in a manual
page be representable in the legacy encoding for that language.
</item>
<tag>12.1</tag>
@@ -418,11 +420,11 @@ Released Mar 2009.
<item>Changelog files must be encoded in UTF-8.
</item>
<tag>4.4</tag>
- <item>Tighten some format requirements for changelog files from a should
+ <item>Tightened some format requirements for changelog files from a should
to a must.
</item>
<tag>4.4.1</tag>
- <item>Remove alternative changelog formats. Debian only supports one
+ <item>Removed alternative changelog formats. Debian only supports one
changelog format for the Debian Archive.
</item>
<tag>4.9.1</tag>
@@ -509,14 +511,14 @@ Released Jun 2008.
named in Breaks is deconfigured first. This field should not be
used until the dpkg in Debian stable supports it.
<tag>8.1, 8.2</tag>
-<item>Clarify which files should go into a shared library package, into a
- separate package, or into the -dev package. Suggest -tools instead
+<item>Clarified which files should go into a shared library package, into a
+ separate package, or into the -dev package. Suggests -tools instead
of -runtime for runtime support programs, since that naming is more
common in Debian.
<tag>9.5</tag>
<item>Files in <file>/etc/cron.{hourly,daily,weekly,monthly}</file> must be
- configuration files (upgraded from should). Mention the hourly
- directory.
+ configuration files (upgraded from should). Mentions the hourly
+ directory.
<tag>11.8.6</tag>
<item>Packages providing <file>/etc/X11/Xresources</file> files need not
conflict with <tt> xbase (<< 3.3.2.3a-2)</tt>, which is
--
1.7.5.rc0
Reply to: