# HG changeset patch
# User Karl Berry <karl@freefriends.org>
# Date 1268068917 28800
# Node ID 85ed9679cfa7ef8ae9041fbd756027ca6801fa10
# Parent  ada2df25e40c0608643c05e3f2f6b3a55eec420a
describe third option of committing gnulib files while skipping others

diff --git a/ChangeLog b/ChangeLog
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2010-03-08  Karl Berry  <karl@gnu.org>
+
+	* doc/gnulib-tool.texi (VCS Issues): Mention third option
+	of committing gnulib files while skipping others.
+
 2010-03-07  Bruno Haible  <bruno@clisp.org>
 
 	Tests of module 'wctype' in C++ mode.
diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi
--- a/doc/gnulib-tool.texi
+++ b/doc/gnulib-tool.texi
@@ -545,35 +545,41 @@
 @section Issues with Version Control Systems
 
 If a project stores its source files in a version control system (VCS),
-such as CVS, SVN, or Git, one needs to decide which files to commit.
+such as CVS, Subversion, or Git, one needs to decide which files to commit.
 
-All files created by @code{gnulib-tool}, except @file{gnulib-cache.m4},
-should be treated like generated source files, like for example a
-@file{parser.c} file is generated from @file{parser.y}.
+In principle, all files created by @code{gnulib-tool}, except
+@file{gnulib-cache.m4}, can be treated like generated source files,
+like for example a @file{parser.c} file generated from
+@file{parser.y}.  Alternatively, they can be considered source files
+and updated manually.
 
-@itemize
+Here are the three different approaches in common use.  Each has its
+place, and you should use whichever best suits your particular project
+and development methods.
 
+@enumerate
 @item
-In projects which commit all source files, whether generated or not, into
-their VCS, the @code{gnulib-tool} generated files should all be committed.
-In this case, you also pass the option @samp{--no-vc-files} to
-@code{gnulib-tool}.
+In projects which commit all source files, whether generated or not,
+into their VCS, the @code{gnulib-tool} generated files should all be
+committed.  In this case, you should pass the option
+@samp{--no-vc-files} to @code{gnulib-tool}, which avoids alteration of
+VCS-related files such as @file{.cvsignore}.
 
 Gnulib also contains files generated by @command{make} (and removed by
-@code{make clean}), using information determined by @command{configure}.
-They should not be checked into the VCS, but instead added to
-@file{.gitignore} or @file{.cvsignore}.
-When you have a Gnulib source file of the form @file{lib/foo.in.h}, the
-corresponding @file{lib/foo.h} is such a file.
+@code{make clean}), using information determined by
+@command{configure}.  For a Gnulib source file of the form
+@file{lib/foo.in.h}, the corresponding @file{lib/foo.h} is such a
+@command{make}-generated file.  These should @emph{not} be checked
+into the VCS, but instead added to @file{.cvsignore} or equivalent.
 
 @item
-In projects which customarily omit from their VCS all files that are generated
-from other source files, all these files and directories would not be
-added into the VCS.  The only file that must be added to the VCS is
-@file{gnulib-cache.m4} in the M4 macros directory.  Also, the script for
-restoring files not in the VCS, customarily called @file{autogen.sh} or
-@file{bootstrap.sh}, will typically contain the statement for restoring
-the omitted files:
+In projects which customarily omit from their VCS all files that are
+generated from other source files, none of these files and directories
+are added into the VCS.  The only file that must be added to the VCS
+is @file{gnulib-cache.m4} in the M4 macros directory.  Also, the
+script for restoring files not in the VCS, customarily called
+@file{autogen.sh} or @file{bootstrap.sh}, will typically contain the
+statement for restoring the omitted files:
 
 @smallexample
 $ gnulib-tool --update
@@ -584,7 +590,19 @@
 Also it does not report in the ChangeLogs the files that it had to add
 because they were missing.
 
-@end itemize
+@item
+Some projects take a ``middle road'': they do commit Gnulib source
+files as in the first approach, but they do not commit other derived
+files, such as a @code{Makefile.in} generated by Automake.  This
+increases the size and complexity of the repository, but can help
+occasional contributors by not requiring them to have a full Gnulib
+checkout to do a build, and all developers by ensuring that all
+developers are working with the same version of Gnulib in the
+repository.  It also supports multiple Gnulib instances within a
+project.  It remains important not to commit the
+@command{make}-generated files, as described above.
+
+@end enumerate
 
 
 @node Unit tests