[Findutils-patches] [PATCH 3/3] Added a maintenance manual.

[James Youngman]

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

        Added a maintenance manual.
        * doc/find-maint.texi: New file.
        * doc/Makefile.am (info_TEXINFOS): Added doc/find-main.texi.
        * doc/find.texi (Introduction): Fixed typo.

Signed-off-by: James Youngman <address@hidden>
Signed-off-by: James Youngman <address@hidden>
---
 NEWS                |    3 +
 doc/Makefile.am     |    5 +-
 doc/find-maint.texi |  268 +++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/find.texi       |    2 +-
 4 files changed, 275 insertions(+), 3 deletions(-)

diff --git a/NEWS b/NEWS
index 82a6d9b..cd1e981 100644
--- a/NEWS
+++ b/NEWS
@@ -15,6 +15,9 @@ several fields.
 Also explain that when reporting a bug, you should check the most
 recent findutils release first.
 
+Introduced doc/find-maint.texi, a maintenance manual for findutils.
+
+
 * Major changes in release 4.3.8
 
 ** Bug Fixes
diff --git a/doc/Makefile.am b/doc/Makefile.am
index ec70e4f..55b5724 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,5 +1,6 @@
-info_TEXINFOS = find.texi
-find_TEXINFOS = perm.texi getdate.texi regexprops.texi
+info_TEXINFOS = find.texi find-maint.texi
+find_TEXINFOS = perm.texi getdate.texi regexprops.texi 
+find_maint_TEXINFOS = 
 MOSTLYCLEANFILES = find.cps 
 CLEANFILES = find.txt find_mono.html findutils.texi_html_node.tar.gz
 
diff --git a/doc/find-maint.texi b/doc/find-maint.texi
new file mode 100644
index 0000000..5122bb3
--- /dev/null
+++ b/doc/find-maint.texi
@@ -0,0 +1,268 @@
+\input texinfo @c -*-texinfo-*-
address@hidden %**start of header
address@hidden find.info
address@hidden Maintaining Findutils
address@hidden For double-sided printing, uncomment:
address@hidden @setchapternewpage odd
address@hidden %**end of header
+
address@hidden version-maint.texi
+
address@hidden
address@hidden
address@hidden iftex
+
address@hidden GNU organization
address@hidden
+* Maintaining Findutils: (find-maint).        Maintaining GNU findutils
address@hidden direntry
+
address@hidden
+This manual explains how GNU findutils is maintained, how changes should
+be made and tested, and what resources exist to help developers.
+
+This is edition @value{EDITION}, for findutils version @value{VERSION}.
+
+Copyright @copyright{} 2007 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no
+Front-Cover Texts, and with no Back-Cover Texts.
+A copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
address@hidden copying
+
address@hidden
address@hidden Maintaining Findutils
address@hidden Edition @value{EDITION}, for GNU findutils version 
@value{VERSION}
address@hidden @value{UPDATED}
address@hidden by James Youngman
+
address@hidden
address@hidden 0pt plus 1filll
address@hidden
address@hidden titlepage
+
address@hidden
+
address@hidden
address@hidden Top, Introduction, (dir), (dir)
address@hidden Maintaining GNU Findutils
+
address@hidden
address@hidden ifnottex
+
address@hidden
+* Introduction::
+* Maintaining GNU Programs::
+* General Considerations::
+* Tools::
+* Using Gnulib::
+* Documentation::
+* Testing::
+* Internationalisation::
+* Security::
+* Making Releases::
address@hidden menu
+
+
+
+
+
address@hidden Introduction
address@hidden 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.
+
+
address@hidden Maintaining GNU Programs
address@hidden Maintaining GNU Programs
+
+GNU Findutils is part of the GNU Project and so there are a number of
+documents which set out standards for the maintenance of GNU
+software.  
+
address@hidden @file
address@hidden standards.texi
+GNU Project Coding Standards.  All changes to findutils should comply
+with these standards.  In some areas we go somewhat beyond the
+requirements of the standards, but these cases are explained in this
+manual.
address@hidden maintain.texi
+Information for Maintainers of GNU Software.  This document provides
+guidance for GNU maintainers.  Everybody with commit access should
+read this document.   Everybody else is welcome to do so too, of
+course.
address@hidden table
+
+
+
address@hidden General Considerations
address@hidden General Considerations
+
+The findutils package is installed on many many systems, usually as a
+fundamental component.  The programs in the package are often used in
+order to successfully boot or fix the system.
+
+This fact means that for findutils we bear in mind considerations that
+may not apply so much as for other packages.  For example, the fact
+that findutils is often a base component motivates us to
address@hidden
address@hidden Limit dependencies on libraries
address@hidden Avoid dependencies on other large packages (for example, 
interpreters)
address@hidden Be conservative when making changes to the 'stable' release 
branch
address@hidden itemize
+
+All those considerations come before functionality.  Functional
+enhancements are still made to findutils, but these are almost
+exclusively introduced in the 'development' release branch, to allow
+extensive testing and proving.
+
+Sometimes it is useful to have a priority list to provide guidance
+when making design trade-offs.   For findutils, that priority list is:
+
address@hidden
address@hidden Correctness
address@hidden Standards compliance
address@hidden Security
address@hidden Backward compatibility
address@hidden Performance
address@hidden Functionality
address@hidden enumerate
+
+For example, we support the @code{-exec} action because POSIX
+compliance requires this, even though there are security problems with
+it and we would otherwise prefer people to use @code{-execdir}.  There
+are also cases where some performance is sacrificed in the name of
+security.  For example, the sanity checks that @code{find} performs
+while traversing a directory tree may slow it down.   We adopt
+functional changes, and functional changes are allowed to make
address@hidden slower, but only if there is no detectable impact on users
+who don't use the feature.  
+
+Backward-incompatible changes do get made in order to comply with
+standards (for example the behaviour of @code{-perm -...} changed in
+order to comply with POSIX).  However, they don't get made in order to
+provide better ease of use; for example the semantics of @code{-size
+-2G} are almost always unexpected by users, but we retain the current
+behaviour because of backward compatibility and for its similarity to
+the block-rounding behaviour of @code{-size -30}.  We might introduce
+a change which does not have the unfortunate rounding behaviour, but
+we would choose another syntax (for example @code{-size '<2G'}) for
+this.
+
+
+
address@hidden Installed on many systems
address@hidden Often part of base
address@hidden Needs to work on broken systems (e.g. unresponsive NFS servers,
address@hidden mode-0 files)
+
address@hidden Tools
address@hidden 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 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
address@hidden) shows what system calls are being made.   Using this
+information we can work to remove unnecessary file system operations.
+
address@hidden Valgrind
+Valgrind is a tool which dynamically verifies the memory accesses a
+program makes to ensure that they are valid (for example, that the
+behaviour of the program does not in any way depend on the contents of
+uninitialised memory).  
+
address@hidden DejaGnu
+DejaGnu is the test framework used to run the findutils test suite
+(the @code{runtest} program is part of DejaGnu).  It would be ideal if
+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 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 Documentation
address@hidden Documentation
+This section will explain which files should be updated when the code
+changes, and what documentation exists.
+
+
address@hidden Testing
address@hidden Testing
+This chapter will explain the general procedures for adding tests to
+the test suite, and the functions defined in the findutils-specific
+DejaGnu configuration.  Where appropriate references will be made to
+the DejaGnu documentation.
+
+
address@hidden Internationalisation
address@hidden Internationalisation
+Explain how we interact with the GNU Translation Project.
+
+
address@hidden Security
address@hidden Security
+Outline the general nature of the security considerations (making
+reference to find.texi) and how we generally deal with security
+problems.
+
+
address@hidden Making Releases
address@hidden Making Releases
+This section till explain how to make a findutils release.
+
address@hidden fn
+
address@hidden
+
address@hidden texi related words used by Emacs' spell checker ispell.el
+
address@hidden LocalWords: texinfo setfilename settitle setchapternewpage
address@hidden LocalWords: iftex finalout ifinfo DIR titlepage vskip pt
address@hidden LocalWords: filll dir samp dfn noindent xref pxref
address@hidden LocalWords: var deffn texi deffnx itemx emph asis
address@hidden LocalWords: findex smallexample subsubsection cindex
address@hidden LocalWords: dircategory direntry itemize
+
address@hidden other words used by Emacs' spell checker ispell.el
address@hidden LocalWords: README fred updatedb xargs Plett Rendell akefile
address@hidden LocalWords: args grep Filesystems fo foo fOo wildcards iname
address@hidden LocalWords: ipath regex iregex expr fubar regexps
address@hidden LocalWords: metacharacters macs sr sc inode lname ilname
address@hidden LocalWords: sysdep noleaf ls inum xdev filesystems usr atime
address@hidden LocalWords: ctime mtime amin cmin mmin al daystart Sladkey rm
address@hidden LocalWords: anewer cnewer bckw rf xtype uname gname uid gid
address@hidden LocalWords: nouser nogroup chown chgrp perm ch maxdepth
address@hidden LocalWords: mindepth cpio src CD AFS statted stat fstype ufs
address@hidden LocalWords: nfs tmp mfs printf fprint dils rw djm Nov lwall
address@hidden LocalWords: POSIXLY fls fprintf strftime locale's EDT GMT AP
address@hidden LocalWords: EST diff perl backquotes sprintf Falstad Oct cron
address@hidden LocalWords: eg vmunix mkdir afs allexec allwrite ARG bigram
address@hidden LocalWords: bigrams cd chmod comp crc CVS dbfile dum eof
address@hidden LocalWords: fileserver filesystem fn frcode Ghazi Hnewc iXX
address@hidden LocalWords: joeuser Kaveh localpaths localuser LOGNAME
address@hidden LocalWords: Meyering mv netpaths netuser nonblank nonblanks
address@hidden LocalWords: ois ok Pinard printindex proc procs prunefs
address@hidden LocalWords: prunepaths pwd RFS rmadillo rmdir rsh sbins str
address@hidden LocalWords: su Timar ubins ug unstripped vf VM Weitzel
address@hidden LocalWords: wildcard zlogout basename execdir wholename 
iwholename
address@hidden LocalWords: timestamp timestamps Solaris FreeBSD OpenBSD POSIX
diff --git a/doc/find.texi b/doc/find.texi
index 68e53d6..a2954ff 100644
--- a/doc/find.texi
+++ b/doc/find.texi
@@ -157,7 +157,7 @@ part of the GNU/Linux 'distribution', the distributions 
often lag
 seriously behind findutils releases, even the stable release.  Please
 check the GNU FTP site.
 
-menu
address@hidden
 * Scope::
 * Overview::
 * find Expressions::
-- 
1.5.2.1