[Findutils-patches] [PATCH 15/19] Provide more detailed help on how to work with the git sources.

[James Youngman]

Provide more detailed help on how to work with the git sources.
* README-CVS: Rename to README-hacking.
* README-hacking: Add more specific information about using topic
branches, test cases, documentation, coding standards and how to
submit patches.   Much of this is adapted from the files
README-hacking and HACKING in the coreutils source tree.
* Makefile.am: Generate tool-versions.txt, which is a list of the
--version outputs of the tools that the maintainer used to build a
release.
* NEWS: Mention these improvements.

Signed-off-by: James Youngman <address@hidden>
---
 ChangeLog      |   11 +++
 Makefile.am    |   13 +++-
 NEWS           |    4 +-
 README-CVS     |   52 --------------
 README-hacking |  213 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 238 insertions(+), 55 deletions(-)
 delete mode 100644 README-CVS
 create mode 100644 README-hacking

diff --git a/ChangeLog b/ChangeLog
index 3e1bb7c..3cd8c6c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -31,6 +31,17 @@
        ended up in the wrong section when I resolved an earlier merge
        conflict.
 
+       Provide more detailed help on how to work with the git sources.
+       * README-CVS: Rename to README-hacking.
+       * README-hacking: Add more specific information about using topic
+       branches, test cases, documentation, coding standards and how to
+       submit patches.   Much of this is adapted from the files
+       README-hacking and HACKING in the coreutils source tree.
+       * Makefile.am: Generate tool-versions.txt, which is a list of the
+       --version outputs of the tools that the maintainer used to build a
+       release.
+       * NEWS: Mention these improvements.
+
 2009-04-10  Stepan Kasal  <address@hidden>
 
        Backport a fix from 4.5.x.
diff --git a/Makefile.am b/Makefile.am
index 63bc388..3086058 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -2,7 +2,9 @@ AUTOMAKE_OPTIONS=gnits
 # readme-alpha
 
 EXTRA_DIST = COPYING ChangeLog TODO config.h.in stamp-h.in \
-               THANKS import-gnulib.sh import-gnulib.config
+               THANKS import-gnulib.sh import-gnulib.config \
+               tool-versions.txt README-hacking
+
 # "tests" is the gnulib unit test dir.
 SUBDIRS = gnulib tests build-aux lib find xargs locate doc po m4 
 
@@ -12,6 +14,15 @@ TESTFILE_SUFFIXES = .exp .xo .xe .xi
 
 # CONFIG_CLEAN_FILES = gnulib/lib/regex.c
 
+tool-versions.txt: Makefile
+       ( automake --version ; echo ; \
+       autoconf --version ; echo ; \
+       $(CC) --version ; echo ; \
+       m4 --version ; echo ; \
+       gettext --version ; echo ; \
+       runtest --version ; echo ; \
+       makeinfo --version ) > $@
+
 
 # DISTCLEANFILES = intl/libintl.h
 
diff --git a/NEWS b/NEWS
index c544aae..743e7c2 100644
--- a/NEWS
+++ b/NEWS
@@ -51,14 +51,14 @@ from the -ok action are interpreted.
 Added a worked example describing how to find the shallowest instances
 of a given directory name (or names) in a directory hierarchy.
 
+The file README-CVS has been renamed to README-hacking and improved.
+
 ** Translations
 
 Updated translations: Catalan, French, German, Indonesian, Irish,
 Dutch, Polish, Slovenian, Swedish, Vietnamese, Chinese (simplified),
 Lithuanian.
 
-New translations: Czech, Lithuanian. 
-
 * Major changes in release 4.4.0, 2008-03-15
 
 The 4.4.0 release of findutils is a stable release, succeeding the
diff --git a/README-CVS b/README-CVS
deleted file mode 100644
index fb6e90b..0000000
--- a/README-CVS
+++ /dev/null
@@ -1,52 +0,0 @@
-This file describes how to build findutils starting from a set of code
-checked out of CVS, rather than from a released source distribution.
-
-1. Prerequisites
- * CVS (to check out findutils itself)
- * git (to check out the gnulib code)
- * A C compiler, linker and software development libraries (the standard
-   C library)
- * GNU Autoconf version 2.61 or later (earlier versions *may* work)
- * GNU Automake version 1.9 or later (earlier versions *may* work)
- * GNU m4 version 1.4 or later
- * GNU gettext (unless you use configure --disable-nls)
-
-2. Generate a gnulib installation within the findutils source tree
-
- Change your working directory to the findutils source directory (that 
- is, the directory containing this file).   Then run the following 
- command:-
-
-    sh import-gnulib.sh   
-
- This command will use CVS to check out the version of gnulib which is
- intended to work with the findutils source you already have, as
- configured by the file import-gnulib.config.  The gnulib code itself
- is left in the directory "gnulib-git".  The "gnulib" directory
- contains just the gnulib files that findutils needs during the build
- process.
-
- If you want to build findutils with a different version of gnulib,
- just edit import-gnulib.config to change the version and then re-run
- import-gnulib.sh.  When specifying the version, you can specify
- either the date or a CVS tag.  If making any kind of release, please
- use a fully identifying version (rather than just, say, "HEAD").
-
- The import-gnulib.sh script will also run Autoconf and Automake to
- generate the "configure" script and "Makefile.in" files.  Should you 
- need to do this manually, you can do it like this :-
-
-    aclocal -I m4 -I gnulib/m4     && \
-    autoheader                    && \
-    autoconf                      && \
-    automake --add-missing --copy
-
-3. (Optional) Update the translations
-
-    rsync -Lrtvz  translationproject.org::tp/latest/findutils/ po
-
-3. Run "configure" and "make" in the normal way.  
-
- If you have GNU libintl installed, you can just run "configure".
- Otherwise, run "configure --disable-nls".
-
diff --git a/README-hacking b/README-hacking
new file mode 100644
index 0000000..224fb2e
--- /dev/null
+++ b/README-hacking
@@ -0,0 +1,213 @@
+These notes intend to help people working on the checked-out sources.
+They don't apply when you are building from a distribution tarball.
+
+If you want to submit a patch, please start from checked-out sources
+rather than the source tarball.
+
+
+Prerequisites
+=============
+
+ * git (to check out both findutils and gnulib).
+ * A C compiler, linker and software development libraries (the standard
+   C library).  Any compiler compliant with the 1990 ICO C standard running
+   on a POSIX system should work.
+ * GNU Autoconf
+ * GNU Automake
+ * GNU m4
+ * GNU gettext
+ * GNU Dejagnu
+
+The configure program should tell you if you try to use a version of
+one of these tools which is not oif a recent enough version.  The file
+tool-versions.txt indicates which version of each tool the current
+release was built and tested with.
+
+
+Use the latest upstream sources
+===============================
+
+1. Check out the findutils code
+
+  git clone git://git.sv.gnu.org/findutils
+
+This will download the whole repository, it's about 14MB.  If you
+already have a copy you can refresh it with
+
+  git checkout master  (to switch to your copy of the master branch)
+  git pull (to collect and merge changes)
+
+2. Generate a gnulib installation within the findutils source tree
+
+ Change your working directory to the findutils source directory (that
+ is, the directory containing this file).   Then run the following
+ command:-
+
+    sh import-gnulib.sh
+
+ This command will use git to check out the version of gnulib which is
+ intended to work with the findutils source you already have, as
+ configured by the file import-gnulib.config.  The gnulib code itself
+ is left in the directory "gnulib-git".  The "gnulib" directory
+ contains just the gnulib files that findutils needs during the build
+ process.
+
+ If you want to build findutils with a different version of gnulib,
+ just edit import-gnulib.config to change the version and then re-run
+ import-gnulib.sh.  When specifying the version, you can specify
+ either the date or a tag.  If making any kind of release, please
+ use a fully identifying version (rather than just, say, "HEAD").
+
+ The import-gnulib.sh script will also run Autoconf and Automake to
+ generate the "configure" script and "Makefile.in" files.  Should you
+ need to do this manually, you can do it like this :-
+
+    aclocal -I m4 -I gnulib/m4     && \
+    autoheader                    && \
+    autoconf                      && \
+    automake --add-missing --copy
+
+3. (Optional) Update the translations
+
+    rsync -Lrtvz  translationproject.org::tp/latest/findutils/ po
+
+3. Run "configure" and "make" in the normal way.
+
+ If you have GNU libintl installed, you can just run "configure".
+ Otherwise, run "configure --disable-nls".
+
+You are now at the point where your local directory looks just like it
+would after building a source release, except that your copy is more
+up-to-date.
+
+*Before* you commit changes
+===========================
+
+In this project, we much prefer patches that automatically record
+authorship.  That is important not just to give credit where due, but
+also from a legal standpoint (see below).  To create author-annotated
+patches with git, you must first tell git who you are.  That information
+is best recorded in your ~/.gitconfig file.  Edit that file, creating
+it if needed, and put your name and email address in place of these
+example values:
+
+[user]
+  name = Joe X. User
+  email = address@hidden
+
+
+Making commits locally
+======================
+
+You will normally find it much easier to work on a branch.  This
+allows you to maintain your changes and test them without being
+affected by changes on the trunk.
+
+To Make a "topic" branch for your change, do this:
+
+  git branch my-topic
+  git checkout my-topic
+
+You can then work on your branch as normal.
+
+To update your local repository, do this:
+
+  git checkout master
+  git pull
+
+Then, rebase your topic branch to take into account the upstream
+changes you just pulled:
+
+  git checkout my-topic
+  git rebase master
+
+There are some useful checks that git commit hooks will do for you,
+it's a good idea to enable these:
+
+  chmod +x .git/hooks/pre-commit
+
+
+Submitting patches
+==================
+
+If you plan to submit changes to findutils, please make sure you have
+read the GNU coding standard (http://www.gnu.org/prep/standards/).
+Some common things you might have forgotten to do are:
+
+ - document your change in both the manual pages and the Texinfo file
+ - re-run the test suite (with Dejagnu installed!)
+ - add a ChangeLog entry (for now we still do that manually)
+ - add a test case for the bug you're fixing or feature you're adding
+ - mention your fix or change (if it's significant) in the NEWS file
+
+If you have patches, please generate them with "git format-patch" and
+mail them to these addresses:
+
+  address@hidden, address@hidden
+
+Here is a complete session
+
+  # set up your topic branch
+  git checkout master
+  git pull
+  git branch my-topic
+  git checkout my-topic
+
+  # update the code, documentation, test suite and change log, run tests
+  emacs xargs/xargs.c
+  emacs doc/find.texi xargs/xargs.1
+  emacs xargs/testsuite/Makefile.am  xargs/testsuite/xargs.gnu/blah.exp
+  make check
+  emacs ChangeLog NEWS
+
+  # make sure you didn't break anything
+  make distcheck
+
+  # commit the change and send the patches.
+  git add -u
+  git commit
+  git rebase master
+  mkdir /tmp/patches
+  git format-patch -o /tmp/patches master..HEAD
+  git send-email --compose \
+      --to address@hidden \
+      --cc address@hidden /tmp/patches
+
+
+Copyright assignment
+====================
+
+If your change is significant (i.e., if it adds more than ~10 lines),
+then you'll have to have a copyright assignment on file with the FSF.
+Since that involves first an email exchange between you and the FSF,
+and then the exchange (FSF to you, then back) of an actual sheet of paper
+with your signature on it, and finally, some administrative processing
+in Boston, the process can take a few weeks.
+
+The forms to choose from are in gnulib's doc/Copyright/ directory.
+If you want to assign a single change, you should use the file,
+doc/Copyright/request-assign.changes:
+
+    
http://git.sv.gnu.org/gitweb/?p=gnulib.git;a=blob;f=doc/Copyright/request-assign.changes;hb=HEAD
+
+If you would like to assign past and future contributions to a project,
+you'd use doc/Copyright/request-assign.future:
+
+    
http://git.sv.gnu.org/gitweb/?p=gnulib.git;a=blob;f=doc/Copyright/request-assign.future;hb=HEAD
+
+You may make assignments for up to four projects at a time.
+
+In case you're wondering why we bother with all of this, read this:
+
+    http://www.gnu.org/licenses/why-assign.html
+
+
+========================================================================
+Copyright (C) 2009 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 ``GNU Free
+Documentation License'' file as part of this distribution.
-- 
1.5.6.5