find-maint: Documentation
7 Documentation
***************
The findutils git tree includes several different types of
documentation.
7.1 git change log
==================
The git change log for the source tree contains check-in messages which
describe each check-in. These have a standard format:
Summary of the change.
(ChangeLog-style detail)
Here, the format of the detail part follows the standard GNU
ChangeLog style, but without whitespace in the left margin and without
author/date headers. Take a look at the output of 'git log' to see some
examples. The README-hacking file also contains an example with an
explanation.
7.2 User Documentation
======================
User-oriented documentation is provided as manual pages and in Texinfo.
See ⇒Introduction (find)Introduction.
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
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.
The manual pages are suitable for reference use, but the Texinfo manual
should also include introductory and tutorial material.
We make the user documentation available on the web, on the GNU
project web site. These web pages are source-controlled via CVS
(still!). If you are a member of the 'findutils' project on Savannah
you should be able to check the web pages out like this ('$USER' is a
placeholder for your Savannah username):
cvs -d :ext:$USER@cvs.savannah.gnu.org:/web/findutils checkout findutils/manual
You can automatically update the documentation in this repository
using the script 'build-aux/update-online-manual.sh' in the findutils
Git repository.
7.3 Build Guidance
==================
'ABOUT-NLS'
Describes the Free Translation Project, the translation status of
various GNU projects, and how to participate by translating an
application.
'AUTHORS'
Lists the authors of findutils.
'COPYING'
The copyright license covering findutils; currently, the GNU GPL,
version 3.
'INSTALL'
Generic installation instructions for installing GNU programs.
'README'
Information about how to compile findutils in particular
'README-hacking'
Describes how to build findutils from the code in git.
'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.
'TODO'
Mainly obsolete. Please add bugs to the Savannah bug tracker
instead of adding entries to this file.
7.4 Release Information
=======================
'NEWS'
Enumerates the user-visible change in each release. Typical
changes are fixed bugs, functionality changes and documentation
changes. Include the date when a release is made.
'ChangeLog'
This file enumerates all changes to the findutils source code (with
the possible exception of '.cvsignore' and '.gitignore' changes).
The level of detail used for this file should be sufficient to
answer the questions "what changed?" and "why was it changed?".
The file is generated from the git commit messages during 'make
dist'. If a change fixes a bug, always give the bug reference
number in the 'NEWS' file 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
'ChangeLog'. Mention when each release is made.
Info Catalog
find-maint: Using the GNU Portability Library
find-maint: Top
find-maint: Testing