[Findutils-patches] [PATCH] Filled in a large part of find-maint.texi.

[James Youngman]

---
 doc/find-maint.texi |  226 ++++++++++++++++++++++++++++++++++++++++++++++-----
 1 files changed, 204 insertions(+), 22 deletions(-)

diff --git a/doc/find-maint.texi b/doc/find-maint.texi
index 5122bb3..4cb80b9 100644
--- a/doc/find-maint.texi
+++ b/doc/find-maint.texi
@@ -1,12 +1,12 @@
 \input texinfo @c -*-texinfo-*-
 @c %**start of header
address@hidden find.info
address@hidden find-maint.info
 @settitle Maintaining Findutils
 @c For double-sided printing, uncomment:
 @c @setchapternewpage odd
 @c %**end of header
 
address@hidden version-maint.texi
address@hidden versionmaint.texi
 
 @iftex
 @finalout
@@ -59,7 +59,7 @@ Free Documentation License''.
 * Maintaining GNU Programs::
 * General Considerations::
 * Tools::
-* Using Gnulib::
+* Using the GNU Portability Library::
 * Documentation::
 * Testing::
 * Internationalisation::
@@ -73,12 +73,18 @@ Free Documentation License''.
 
 @node Introduction
 @chapter Introduction
-This document explains how to contribute to and maintain GNU Findutils.   It 
concentrates on developer-specific issues.  For information about how to use 
the software please refer to @xref{Introduction, ,Introduction,find,The 
Findutils manual}.
 
-This manual aims to be useful without necessarily being verbose.  If
-you find any part of the document to be so terse as to be unuseful,
-please ask for help on the @email{bug-findutils@@gnu.org} mailing
-list.
+This document explains how to contribute to and maintain GNU
+Findutils.  It concentrates on developer-specific issues.  For
+information about how to use the software please refer to
address@hidden, ,Introduction,find,The Findutils manual}.
+
+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
+be unuseful, please ask for help on the @email{bug-findutils@@gnu.org}
+mailing list.  We'll try to improve this document too.
 
 
 @node Maintaining GNU Programs
@@ -191,20 +197,191 @@ findutils, DejaGnu is invoked a lot. @xref{Testing}, for 
more
 information. 
 @end itemize
 
address@hidden Using Gnulib
address@hidden Using Gnulib
-This section will explain why we use Gnulib, why the Gnulib files are
-not included in the findutils CVS repository, and what this means for
-fixing bugs in those modules.
address@hidden Using the GNU Portability Library
address@hidden 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
+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.
+
+
address@hidden How and Why we Import the Gnulib Code
+Gnnulib does not have a release process which results in a source
+tarball you can download.  Instead, the code is simply made available
+by CVS.  
+
+GNU projects vary in how they interact with Gnulib.  Many import a
+selection of code from Gnulib into the working directory and then
+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,
+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
+for other reasons.
+
+To reduce this uncertainty, I decided to treat Gnulib much like
+Automake.  Files supplied by Automake are simply absent from the
+findutils source tree.  When Automake is run with @code{automake
+--add-missing --copy}, it adds in all the files it thinks should be
+there which aren't there already.
+
+An analogous approach is taken with Gnulib.  The Gnulib code is
+imported from the CVS repository for Gnulib with a findutils helper
+script, @code{import-gnulib.sh}.  That script fetches a copy of the
+Gnulib code into the subdirectory @file{gnulib-cvs} and then runs
address@hidden  The @code{gnulib-tool} program copies the
+required parts of Gnulib into the findutils source tree in the
+subdirectory @file{gnulib}.  This process gives us the property that
+the code in @file{gnulib} and @code{gnulib-cvs} is not included in the
+findutils CVS tree.   Both directories are listed in @file{.cvsignore}
+and so CVS ignores them.
+
+Findutils does not use all the Gnulib code.  The modules we need are
+listed in the file @file{import-gnulib.config}.  The same file also
+indicates the version of Gnulib that we want to use.  Since Gnulib has
+no actual release process, we just use a date.  Both
address@hidden and @file{import-gnulib.config} are in the
+findutils CVS repository.
+
+The upshot of all this is that we can use the findutils CVS repository
+to track which version of Gnulib every findutils release uses.  That
+information is also provided when the user invokes a findutils program
+with the @samp{--version} option.  It also means that if a file exists
+in the Findutils CVS repository, you can be certain that the file
+exists in the CVS repository and is different from a similar file
+elsewhere, it's for a reason.
+
+There are a small number of exceptions to this; the standard
+boiler-plate GNU files such as @file{ABOUT-NLS}, @file{INSTALL} and
address@hidden
+
+
address@hidden How We Fix Gnulib Bugs
+If we always directly import the Gnulib code directly from the CVS
+repository in this way, it is impossible to maintain a locally
+different copy of Gnulib.  This is often a benefit in that accidental
+version skew is prevented.
+
+However, sometimes we want deliberate version skew in order to use a
+findutils-specific patched version of a Gnulib file, for example
+because we fixed a bug.  
+
+Gnulib is used by quite a number of GNU projects, and this means that
+it gets plenty of testing.  Therefore there are relatively few bugs in
+the Gnulib code, but it does happen from time to time.
+
+However, since there is no waiting around for a Gnulib source release
+tarball, Gnulib bugs are generally fixed quickly.  Here is an outline
+of the way we would contribute a fix to Gnulib (assuming you know it
+is not already fixed in current Gnulib CVS):
+
address@hidden @asis
address@hidden Check you already completed a copyright assignment for Gnulib
address@hidden Begin with a vanilla CVS tree
+Download the Findutils source code from CVS (or use the tree you have
+already)
address@hidden Check out a copy of the Gnulib source
+An easy way to do this is to simply use @code{cp -ar} on the
address@hidden directory.   Have the Gnulib code checked out
+somewhere @emph{outside} your working CVS tree for findutils.
address@hidden Import Gnulib from your local copy
+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.
address@hidden 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.  
address@hidden Write a test case
+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.
address@hidden Fix the Gnulib bug
+Make sure your editor follows symbolic links so that your changes to
address@hidden/...} actually affect the files in the CVS working
+directory you checked out earlier.   Observe that your test now passes.
address@hidden Prepare a Gnulib patch
+Use @code{cvs -z3 diff -upN} to prepare the patch.  Write a ChangeLog
+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.  
address@hidden Wait for the patch to be applied
+Once your bugfix 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.  
address@hidden 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.
address@hidden table
+
address@hidden Documentation
address@hidden Documentation
 
+The findutils CVS tree includes several different types of
+documentation.
 
address@hidden 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.  
 
+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.
+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.
 
address@hidden Documentation
address@hidden Documentation
-This section will explain which files should be updated when the code
-changes, and what documentation exists.
 
address@hidden Build Guidance
+
address@hidden @file
address@hidden ABOUT-NLS
+Describes the Free Translation Project, the translation status of
+various GNU projects, and how to participate by translating an
+application.  
address@hidden AUTHORS
+Lists the authors of findutils.
address@hidden COPYING
+The copyright license covering findutils; currently, the GNU GPL,
+version 2.
address@hidden INSTALL
+Generic installation instructions for installing GNU programs.
address@hidden README
+Information about how to compile findutils in particular
address@hidden README-alpha
+A README file which is included with testing releases of findutils.
address@hidden README-CVS
+Describes how to build findutils from the code in CVS.
address@hidden THANKS
+Thanks for people who contributed to findutils.  Generally, if
+someone's contribution was significant enough to need a copyright
+assignment, their name should go in here.
address@hidden TODO
+Mainly obsolete.
address@hidden table
+
+
address@hidden Release Information
address@hidden @file
address@hidden NEWS
+Enumerates the user-visible change in each release.  Typical changes
+are fixed bugs, functionality changes and documentation changes.
address@hidden ChangeLog
+This file enumerates all changes to the findutils source code (with
+the possible exception of @file{.cvsignore} and @code{.gitignore}
+changes).  
address@hidden table
 
 @node Testing
 @chapter Testing
@@ -216,19 +393,24 @@ the DejaGnu documentation.
 
 @node Internationalisation
 @chapter Internationalisation
-Explain how we interact with the GNU Translation Project.
+Translation is essentially automated from the maintainer's point of
+view.  The TP mails the maintainer when a new PO file is available,
+and we just download it and check it in.  We copy the @file{.po} files
+into the CVS repository.  For more information, please see
address@hidden://www.iro.umontreal.ca/translation/HTML/domain-findutils.html}.
 
 
 @node Security
 @chapter Security
-Outline the general nature of the security considerations (making
-reference to find.texi) and how we generally deal with security
-problems.
+
+See @ref{Security Considerations, ,Security Considerations,find,The
+Findutils manual}, for a full description of the findutils approach to
+security considerations and discussion of particular tools.
 
 
 @node Making Releases
 @chapter Making Releases
-This section till explain how to make a findutils release.
+This section will explain how to make a findutils release.
 
 @printindex fn
 
-- 
1.5.2.1