[Findutils-patches] [PATCH] Document coding conventions often used in findutils.

[James Youngman]

2007-06-27  James Youngman  <address@hidden>

        * doc/find-maint.texi (Coding Conventions): Document coding
        conventions often used in findutils.

Signed-off-by: James Youngman <address@hidden>
---
 ChangeLog           |    3 +
 doc/find-maint.texi |  425 ++++++++++++++++++++++++++++++++++++++++++---------
 2 files changed, 358 insertions(+), 70 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 4b4c71e..bd353d9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,8 @@
 2007-06-27  James Youngman  <address@hidden>
 
+       * doc/find-maint.texi (Coding Conventions): Document coding
+       conventions often used in findutils.
+
        * find/find.1 (EXAMPLES): Added an example of using find and cpio -p
        to copy a directory tree, with pruning and omitted files.
 
diff --git a/doc/find-maint.texi b/doc/find-maint.texi
index a438620..1a15966 100644
--- a/doc/find-maint.texi
+++ b/doc/find-maint.texi
@@ -57,7 +57,8 @@ Free Documentation License''.
 @menu
 * Introduction::
 * Maintaining GNU Programs::
-* General Considerations::
+* Design Issues::
+* Coding Conventions::
 * Tools::
 * Using the GNU Portability Library::
 * Documentation::
@@ -84,7 +85,7 @@ information about how to use the software please refer to
 This manual aims to be useful without necessarily being verbose.  It's
 also a recent document, so there will be a many areas in which
 improvements can be made.  If you find that the document misses out
-important information ot any part of the document is be so terse as to
+important information or any part of the document is be so terse as to
 be unuseful, please ask for help on the @email{bug-findutils@@gnu.org}
 mailing list.  We'll try to improve this document too.
 
@@ -111,8 +112,8 @@ course.
 
 
 
address@hidden General Considerations
address@hidden General Considerations
address@hidden Design Issues
address@hidden Design Issues
 
 The findutils package is installed on many many systems, usually as a
 fundamental component.  The programs in the package are often used in
@@ -165,6 +166,24 @@ a change which does not have the unfortunate rounding 
behaviour, but
 we would choose another syntax (for example @code{-size '<2G'}) for
 this.
 
+In a general sense, we try to do test-driven development of the
+findutils code; that is, we try to implement test cases for new
+features and bug fixes before modifying the code to make the test
+pass.  Some features of the code are tested well, but the test
+coverage for other features is less good.  If you are about to modify
+the code for a predicate and aren't sure about the test coverage, use
address@hidden on the test directories and measure the coverage with
address@hidden or another test coverage tool.  
+
+Lastly, we try not to depend on having a ``working system''.  The
+findutils suite is used for diagnosis of problems, and this applies
+especially to @code{find}.  We should ensure that @code{find} still
+works on relatively broken systems, for example systems with damaged
address@hidden/etc/passwd} files.  Another interesting example is the case
+where a system is a client of one or more unresponsive NFS servers.
+On such a system, if you try to stat all mount points, your program
+will hang indefinitely, waiting for the remote NFS server to respond.
+
 
 
 @c Installed on many systems
@@ -172,12 +191,264 @@ this.
 @c Needs to work on broken systems (e.g. unresponsive NFS servers,
 @c mode-0 files)
 
address@hidden Coding Conventions
address@hidden Coding Conventions
+
+Coding style documents which set out to establish a uniform look and
+feel to source code have worthy goals, for example greater ease of
+maintenance and readability.  However, I do not believe that in
+general coding style guide authors can envisage every situation, and
+it is always possible that it might on occasion be necessary to break
+the letter of the style guide in order to honour its spirit, or to
+better achieve the style guide's goals.
+
+I've certainly seen many style guides outside the free software world
+which make bald statements such as ``functions shall have exactly one
+return statement''.  The desire to ensure consistency and obviousness
+of control flow is laudable, but it is all too common for such bald
+requirements to be followed unthinkingly.  Certainly I've seen such
+coding standards result in unmaintainable code with terrible
+infelicities such as functions containing @code{if} statements nested
+nine levels deep.  I suppose such coding standards don't survive in
+free software projects because they tend to drive away potential
+contributors or tend to generate heated discussions on mailing lists.
+Equally, a nine-level-deep function in a free software program would
+quickly get refactored, assuming it is obvious what the function is
+supposed to do...
+
+Be that as it may, the approach I will take for this document is to
+explain some idioms and practices in use in the findutils source code,
+and leave it up to the reader's engineering judgement to decide which
+considerations apply to the code they are working on, and whether or
+not there is sufficient reason to ignore the guidance in current
+circumstances.  
+
+
address@hidden
+* Make the Compiler Find the Bugs::
+* The File System Is Being Modified::
+* Don't Trust the File System Contents::
+* Debugging is For Users Too:: 
+* Factor Out Repeated Code::
address@hidden menu
+
address@hidden    Make the Compiler Find the Bugs
address@hidden Make the Compiler Find the Bugs
+
+Finding bugs is tedious.  If I have a filesystem containing two
+million files, and a find command line should print one million of
+them, but in fact it misses out 1%, you can tell the program is
+printing the wrong result only if you know the right answer for that
+filesystem at that time.  If you don't know this, you may just not
+find out about that bug.  For this reason it is important to have a
+comprehensive test suite.
+
+The test suite is of course not the only way to find the bugs.  The
+findutils source code makes liberal use of the assert macro.  While on
+the one hand these might be a performance drain, the performance
+impact of most of these is negligible compared to the time taken to
+fetch even one sector from a disk drive.  
+
+Assertions should not be used to check the results of operations which
+may be affected by the program's external environment.  For example,
+never assert that a file could be opened successfully.  Errors
+relating to problems with the program's execution environment should
+be diagnosed with a user-oriented error message.  An assertion failure
+should always denote a bug in the program.
+
+Several programs in the findutils suite perform self-checks.  See for
+example the function @code{pred_sanity_check} in @file{find/pred.c}.
+This is generally desirable.
+
+There are also a number of small ways in which we can help the
+compiler to find the bugs for us.
+
address@hidden Constants in Equality Testing
+
+It's a common error to write @code{=} when @code{==} is meant.
+Sometimes this happens in new code and is simply due to finger
+trouble.  Sometimes it is the result of the inadvertent deletion of a
+character.  In any case, there is a subset of cases where we can
+persuade the compiler to generate an error message when we make this
+mistake; this is where the equality test is with a constant.
+
+This is an example of a vulnerable piece of code.  
+
address@hidden
+if (x == 2)
+ ...
address@hidden example
+
+A simple typo converts the above into 
+
address@hidden
+if (x = 2)
+ ...
address@hidden example
+
+We've introduced a bug; the condition is always true, and the value of
address@hidden has been changed.  However, a simple change to our practice
+would have made us immune to this problem:
+
address@hidden
+if (2 == x)
+ ...
address@hidden example
+
+Usually, the Emacs keystroke @kbd{M-t} can be used to swap the operands.
+
+
address@hidden Spelling of ASCII NUL
+
+Strings in C are just sequences of characters terminated by a NUL.
+The ASCII NUL character has the numerical value zero.  It is normally
+represented in C code as @samp{\0}.  Here is a typical piece of C
+code:
+
address@hidden
+*p = '\0';
address@hidden example
+
+Consider what happens if there is an unfortunate typo:
+
address@hidden
+*p = '0';
address@hidden example
+
+We have changed the meaning of our program and the compiler cannot
+diagnose this as an error.  Our string is no longer terminated.  Bad
+things will probably happen.  It would be better if the compiler could
+help us diagnose this problem.  
+
+In C, the type of @code{'\0'} is in fact int, not char.  This provides
+us with a simple way to avoid this error.  The constant @code{0} has
+the same value and type as the constant @code{'\0'}.  However, it is
+not as vulnerable to typos.    For this reason I normally prefer to
+use this code:
+
address@hidden
+*p = 0;
address@hidden example
+
+
address@hidden    Factor Out Repeated Code
address@hidden Factor Out Repeated Code
+
+Repeated code imposes a greater maintenance burden and increases the
+exposure to bugs.  For example, if you discover that something you
+want to implement has some similarity with an existing piece of code,
+don't cut and paste it.  Instead, factor the code out.  The risk of
+cutting and pasting the code, particularly if you do this several
+times, is that you end up with several copies of the same code.
+
+If the original code had a bug, you now have N places where this needs
+to be fixed.  It's all to easy to miss some out when trying to fix the
+bug.  Equally, it's quite possible that when pasting the code into
+some function, the pasted code was not quite adapted correctly to its
+new environment.  To pick a contrived example, perhaps it modifies a
+global variable which it that code shouldn't be touching in its new
+home.  Worse, perhaps it makes some unstated assumption about the
+nature of the input arguments which is in fact not true for the
+context of the now duplicated code.
+
+A good example of the use of refactoring in findutils is the
address@hidden function in @file{find/parser.c}.  A less clear-cut
+but larger example is the factoring out of code which would otherwise
+have been duplicated between @file{find/find.c} and
address@hidden/ftsfind.c}.
+
+The findutils test suite is comprehensive enough that refactoring code
+should not generally be a daunting prospect from a testing point of
+view.  Nevertheless there are some areas which are only
+lightly-tested:
+
address@hidden
address@hidden Tests on the ages of files
address@hidden Code which deals with the values returned by operating system 
calls (for example handling of ENOENT)
address@hidden Code dealing with OS limits (for example, limits on path length
+or exec arguments)
address@hidden Code relating to features not all systems have (for example
+Solaris Doors)
address@hidden enumerate
+
+Please exercise caution when working in those areas.
+
+
address@hidden    Debugging is For Users Too 
address@hidden Debugging is For Users Too
+
+Debug and diagnostic code is often used to verify that a program is
+working in the way its author thinks it should be.  But users are
+often uncertain about what a program is doing, too.  Exposing them a
+little more diagnostic information can help.  Much of the diagnostic
+code in @code{find}, for example, is controlled by the @samp{-D} flag,
+as opposed to C preprocessor directives.
+
+Making diagnostic messages available to users also means that the
+phrasing of the diagnostic messages becomes important, too.
+
+
address@hidden    Don't Trust the File System Contents
address@hidden Don't Trust the File System Contents
+
+People use @code{find} to search in directories created by other
+people.  Sometimes they do this to check to suspicious activity (for
+example to look for new setuid binaries).  This means that it would be
+bad if @code{find} were vulnerable to, say, a security problem
+exploitable by constructing a specially-crafted filename.  The same
+consideration would apply to @code{locate} and @code{updatedb}.
+
+Henry Spencer said this well in his fifth commandment:
address@hidden
+Thou shalt check the array bounds of all strings (indeed, all arrays),
+for surely where thou typest @samp{foo} someone someday shall type
address@hidden
address@hidden quotation
+
+Symbolic links can often be a problem.  If @code{find} calls
address@hidden on something and discovers that it is a directory, it's
+normal for @code{find} to recurse into it.  Even if the @code{chdir}
+system call is used immediately, there is still a window of
+opportunity between the @code{lstat} and the @code{chdir} in which a
+malicious person could rename the directory and substitute a symbolic
+link to some other directory.
+
address@hidden    The File System Is Being Modified
address@hidden The File System Is Being Modified
+
+The filesystem gets modified while you are traversing it.  For,
+example, it's normal for files to get deleted while @code{find} is
+traversing a directory.  Issuing an error message seems helpful when a
+file is deleted from the one directory you are interested in, but if
address@hidden is searching 15000 directories, such a message becomes
+less helpful.
+
+Bear in mind also that it is possible for the directory @code{find} is
+currently searching could be moved to another point in the filesystem,
+and that the directory in which @code{find} was started could be
+deleted. 
+
+Henry Spencer's sixth commandment is also apposite here:
address@hidden
+If a function be advertised to return an error code in the event of
+difficulties, thou shalt check for that code, yea, even though the
+checks triple the size of thy code and produce aches in thy typing
+fingers, for if thou thinkest ``it cannot happen to me'', the gods
+shall surely punish thee for thy arrogance.
address@hidden quotation
+
+There are a lot of files out there.  They come in all dates and
+sizes.  There is a condition out there in the real world to exercise
+every bit of the code base.  So we try to test that code base before
+someone falls over a bug.  
+
+
 @node Tools
 @chapter Tools
 Most of the tools required to build findutils are mentioned in the
 file @file{README-CVS}.  We also use some other tools:
 
address@hidden
address@hidden @asis
 @item System call traces
 Much of the execution time of find is spent waiting for filesystem
 operations.  A system call trace (for example, that provided by
@@ -197,20 +468,20 @@ everybody building @code{findutils} also ran the test 
suite, but many
 people don't have DejaGnu installed.  When changes are made to
 findutils, DejaGnu is invoked a lot. @xref{Testing}, for more
 information. 
address@hidden itemize
address@hidden table
 
 @node Using the GNU Portability Library
 @chapter Using the GNU Portability Library
 The Gnulib library (@url{http://www.gnu.org/software/gnulib/}) makes a
 variety of systems look more like a GNU/Linux system and also applies
-a bunch of qutomatic bug fixes and workarounds.  Some of these also
+a bunch of automatic bug fixes and workarounds.  Some of these also
 apply to GNU/Linux systems too.  For example, the Gnulib regex
 implementation is used when we determine that we are building on a
 GNU libc system with a bug in the regex implementation.
 
 
 @section How and Why we Import the Gnulib Code
-Gnnulib does not have a release process which results in a source
+Gnulib does not have a release process which results in a source
 tarball you can download.  Instead, the code is simply made available
 by CVS.  
 
@@ -220,7 +491,7 @@ check the updated files into the CVS repository for their 
project.
 The coreutils project does this, for example.
 
 At the last maintainer changeover for findutils (2003) it turned out
-that there was a lot of material in findutils in common with gnulib,
+that there was a lot of material in findutils in common with Gnulib,
 but it had not been updated in a long time.  It was difficult to
 figure out which source files were intended to track external sources
 and which were intended to contain incompatible changes, or diverge
@@ -296,10 +567,10 @@ The @code{import-gnulib.sh} tool has a @samp{-d} option 
which you can
 use to import the code from a local copy of Gnulib.
 @item Build findutils
 Build findutils and run the test suite, which should pass.  In our
-example we assume you have just noticed a bug in gnulib, not that
-recent gnulib changes broke the findutils regression tests.  
+example we assume you have just noticed a bug in Gnulib, not that
+recent Gnulib changes broke the findutils regression tests.  
 @item Write a test case
-If in fact gnulib did break the findutils regression tests, you can probably
+If in fact Gnulib did break the findutils regression tests, you can probably
 skip this step, since you already have a test case demonstrating the problem.
 Otherwise, write a findutils test case for the bug and/or a Gnulib test case.
 @item Fix the Gnulib bug
@@ -312,16 +583,25 @@ entry and prepend this to the patch.  Check that the 
patch conforms
 with the GNU coding standards, and email it to the Gnulib mailing
 list.  
 @item Wait for the patch to be applied
-Once your bugfix has been applied, you can update your local directory
+Once your bug fix has been applied, you can update your local directory
 from CVS, re-import the code into Findutils (still using the @code{-d}
 option), and re-run the tests.  This verifies that the fix the Gnulib
 team made actually fixes your problem.  
 @item Reimport the Gnulib code
 Update the findutils file @file{import-gnulib.config} to specify a
-date which is after the point at which the bugfix was comitted to
-Gnulib.  Finally, re-import the Gnulib code directly from CVS and run
-the tests again.  This verifies that there was no remaining local
-change that we were relying on to fix the bug.
+date which is after the point at which the bug fix was committed to
+Gnulib.  Finally, re-import the Gnulib code directly from CVS by using
address@hidden without the @samp{-d} option, and run the
+tests again.  This verifies that there was no remaining local change
+that we were relying on to fix the bug.
+
+Be aware of the fact that the date specified in the
address@hidden file selects the latest changes for the
+given date, so if you modify @file{import-gnulib.config} as soon as
+someone tells you they they checked in a bugfix and you set
address@hidden to today's date, there will be some file version
+instability for the rest of the day.
+
 @end table
 
 @node Documentation
@@ -331,18 +611,19 @@ The findutils CVS tree includes several different types of
 documentation.
 
 @section User Documentation
-User-oriented documentation such as
address@hidden,,Introduction,find,The Findutils manual} and the
-manual pages for the various findutils programs are the primary
-documentation.  
+User-oriented documentation is provided as manual pages and in
+Texinfo.  See
address@hidden,,Introduction,find,The Findutils manual}.
 
 Please make sure both sets of documentation are updated if you make a
 change to the code.  The GNU coding standards do not normally call for
-mantaining manual pages on the grounds of effort duplication.
+maintaining manual pages on the grounds of effort duplication.
 However, the manual page format is more convenient for quick
 reference, and so it's worth maintaining both types of documentation.
 However, the manual pages are normally rather more terse than the
-Texinfo documentation.
+Texinfo documentation.  The manual pages are suitable for reference
+use, but the Texinfo manual should also include introductory and
+tutorial material.
 
 
 @section Build Guidance
@@ -382,7 +663,13 @@ are fixed bugs, functionality changes and documentation 
changes.
 @item ChangeLog
 This file enumerates all changes to the findutils source code (with
 the possible exception of @file{.cvsignore} and @code{.gitignore}
-changes).  
+changes).  The level of detail used for this file should be sufficient
+to answer the questions ``what changed?'' and ``why was it changed?''.
+If a change fixes a bug, always give the bug reference number in both
+the @file{ChangeLog} and @file{NEWS} files and of course also in the
+checkin message.  In general, it should be possible to enumerate all
+material changes to a function by searching for its name in
address@hidden
 @end table
 
 @node Testing
@@ -421,7 +708,7 @@ to @samp{Invalid} and close the bug.   Make sure you set the
 @samp{Assigned to} field to yourself before closing the bug.
 
 @item Fixing
-When you commit a bugfix into CVS (or in the case of a contributed
+When you commit a bug fix into CVS (or in the case of a contributed
 patch, commit the change), mark the bug as @samp{Fixed}.  Make sure
 you include a new test case where this is relevant.  If you can figure
 out which releases are affected, please also set the @samp{Release}
@@ -443,7 +730,7 @@ them have a package maintainer who is a member of the 
mailing list.
 Distributions don't often feed back patches to the
 @email{bug-findutils@@gnu.org} list, but on the other hand many of
 their patches relate only to standards for file locations and so
-forth, and are therefore distirbution specific.  On an irregular basis
+forth, and are therefore distribution specific.  On an irregular basis
 I check the current patches being used by one or two distributions,
 but the total number of GNU/Linux distributions is large enough that
 we could not hope to cover them all.
@@ -475,7 +762,7 @@ security considerations and discussion of particular tools.
 
 If someone reports a security bug publicly, we should fix this as
 rapidly as possible.  If necessary, this can mean issuing a fixed
-release containing just the one bugfix.  We try to avoid issuing
+release containing just the one bug fix.  We try to avoid issuing
 releases which include both significant security fixes and functional
 changes.  
 
@@ -487,16 +774,18 @@ way is that we avoid situations where people watching for 
CVS commits
 can figure out and exploit a security problem before a fixed release
 is available. 
 
+It's important that security problems be fixed promptly, but don't
+rush so much that things go wrong.  Make sure the new release really
+fixes the problem.  It's usually best not to include functional
+changes in your security-fix release.
+
 If the security problem is serious, send an alert to
 @email{vendor-sec@@lst.de}.  The members of the list include most
 GNU/Linux distributions.  The point of doing this is to allow them to
 prepare to release your security fix to their customers, once the fix
 becomes available.    Here is an example alert:-
 
address@hidden
------BEGIN PGP SIGNED MESSAGE-----
-Hash: SHA1
-
address@hidden
 GNU findutils heap buffer overrun (potential privilege escalation)
 
 $Revision: 1.5 $; $Date: 2007/05/28 21:15:25 $
@@ -508,7 +797,7 @@ I. BACKGROUND
 GNU findutils is a set of programs which search for files on Unix-like
 systems.  It is maintained by the GNU Project of the Free Software
 Foundation.  For more information, see
-http://www.gnu.org/software/findutils.
address@hidden://www.gnu.org/software/findutils}.
 
 
 II. DESCRIPTION
@@ -552,18 +841,19 @@ IV. DETECTION
 =============
 
 Software
-- --------
+--------
 All existing releases of findutils are affected.
 
 
 Installations
-- -------------
+-------------
 
 To discover the ongest path name on a given system, you can use the
 following command (requires GNU findutils and GNU coreutils):
 
address@hidden
 find / -print0 | tr -c '\0' 'x' | tr '\0' '\n' | wc -L
-
address@hidden verbatim
 
 V. EXAMPLE
 ==========
@@ -577,6 +867,7 @@ determine if a binary is affected.  Therefore running it on 
your
 system may have undesirable effects.  We recommend that you read the
 script before running it.
 
address@hidden
 #! /bin/sh
 set +m
 if vanilla_db="$(mktemp nicedb.XXXXXX)" ; then
@@ -636,7 +927,7 @@ buggy, may or may not be vulnerable: $ver"
 else
   exit 1
 fi
-
address@hidden verbatim
 
 
 
@@ -665,21 +956,21 @@ VII. PATCH
 
 This patch should apply to findutils-4.2.23 and later.
 Findutils-4.2.23 was released almost two years ago.
-
address@hidden
 Index: locate/locate.c
 ===================================================================
 RCS file: /cvsroot/findutils/findutils/locate/locate.c,v
 retrieving revision 1.58.2.2
 diff -u -p -r1.58.2.2 locate.c
-- --- locate/locate.c  22 Apr 2007 16:57:42 -0000      1.58.2.2
+--- locate/locate.c    22 Apr 2007 16:57:42 -0000      1.58.2.2
 +++ locate/locate.c    28 May 2007 10:18:16 -0000
 @@@@ -124,9 +124,9 @@@@ extern int errno;
  
  #include "locatedb.h"
  #include <getline.h>
-- -#include "../gnulib/lib/xalloc.h"
-- -#include "../gnulib/lib/error.h"
-- -#include "../gnulib/lib/human.h"
+-#include "../gnulib/lib/xalloc.h"
+-#include "../gnulib/lib/error.h"
+-#include "../gnulib/lib/human.h"
 +#include "xalloc.h"
 +#include "error.h"
 +#include "human.h"
@@ -719,7 +1010,7 @@ diff -u -p -r1.58.2.2 locate.c
  static int
  visit_old_format(struct process_data *procdata, void *context)
  @{
-- -  register char *s;
+-  register char *s;
 +  register size_t i;
    (void) context;
  
@@ -730,23 +1021,23 @@ diff -u -p -r1.58.2.2 locate.c
      procdata->count += procdata->c - LOCATEDB_OLD_OFFSET;
 +  assert(procdata->count > 0);
  
-- -  /* Overlay the old path with the remainder of the new.  */
-- -  for (s = procdata->original_filename + procdata->count;
+-  /* Overlay the old path with the remainder of the new.  */
+-  for (s = procdata->original_filename + procdata->count;
 +  /* Overlay the old path with the remainder of the new.  Read 
 +   * more data until we get to the next filename.
 +   */
 +  for (i=procdata->count;
         (procdata->c = getc (procdata->fp)) > LOCATEDB_OLD_ESCAPE;)
-- -    if (procdata->c < 0200)
-- -      *s++ = procdata->c;           /* An ordinary character.  */
-- -    else
-- -      @{
-- -    /* Bigram markers have the high bit set. */
-- -    procdata->c &= 0177;
-- -    *s++ = procdata->bigram1[procdata->c];
-- -    *s++ = procdata->bigram2[procdata->c];
-- -      @}
-- -  *s-- = '\0';
+-    if (procdata->c < 0200)
+-      *s++ = procdata->c;             /* An ordinary character.  */
+-    else
+-      @{
+-      /* Bigram markers have the high bit set. */
+-      procdata->c &= 0177;
+-      *s++ = procdata->bigram1[procdata->c];
+-      *s++ = procdata->bigram2[procdata->c];
+-      @}
+-  *s-- = '\0';
 +    @{
 +      if (procdata->c < 0200)
 +      @{
@@ -771,10 +1062,9 @@ diff -u -p -r1.58.2.2 locate.c
 +  procdata->original_filename[i] = 0;
  
    procdata->munged_filename = procdata->original_filename;
-   
-
-
address@hidden verbatim
 
+   
 VIII. THANKS
 ============
 
@@ -787,15 +1077,10 @@ VIII. CVE INFORMATION
 No CVE candidate number has yet been assigned for this vulnerability.
 If someone provides one, I will include it in the public announcement
 and change logs.
------BEGIN PGP SIGNATURE-----
-Version: GnuPG v1.4.6 (GNU/Linux)
-
-iD8DBQFGW0sucqCfqxMUHDYRAntVAKCIt54u8If+gpRtdwf+OHH5F+UUbACeNFWV
-KQ8qLDri26ScoEXXXQn08QA=
-=olFi
------END PGP SIGNATURE-----
address@hidden example
address@hidden smallexample
 
+The original announcement above was sent out with a cleartext PGP
+signature, of course, but that has been omitted from the example.
 
 Once a fixed release is available, announce the new release using the
 normal channels.  Any CVE number assigned for the problem should be
@@ -811,8 +1096,8 @@ time being here is a terse description of the main steps:
 
 @enumerate
 @item Commit changes; make sure your working directory has no
-uncomitted changes.
address@hidden Test; make sure that all changes ou have made have tests, and
+uncommitted changes.
address@hidden Test; make sure that all changes you have made have tests, and
 that the tests pass.  Verify this with @code{make distcheck}.
 @item Bugs; make sure all Savannah bug entries fixed in this release
 are fixed.
@@ -823,9 +1108,9 @@ Copy the tarball somewhere safe.
 @item Tag the release; findutils releases are tagged in CVS as
 FINDUTILS_x_y_z-1.  For example, the tag for findutils release 4.3.8
 is FINDUTILS_4_3_8-1.
address@hidden Prepare the upload and upload it; see the
address@hidden FTP Uploads, ,Automated FTP
-Uploads, maintain, Information for Maintainers of GNU Software}
address@hidden Prepare the upload and upload it.  
address@hidden FTP Uploads, ,Automated FTP
+Uploads, maintain, Information for Maintainers of GNU Software},
 for detailed upload instructions.
 @item Make a release announcement; include an extract from the NEWS
 file which explains what's changed.  Announcements for test releases
-- 
1.5.2.1