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 <[email protected]> --- ChangeLog | 11 +++ Makefile.am | 13 +++- NEWS | 5 ++ README-CVS | 52 -------------- README-hacking | 213 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 241 insertions(+), 53 deletions(-) delete mode 100644 README-CVS create mode 100644 README-hacking diff --git a/ChangeLog b/ChangeLog index 199ea8d..5a692d0 100644 --- a/ChangeLog +++ b/ChangeLog @@ -7,6 +7,17 @@ configure. * NEWS: Mention this bugfix. + 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-03-04 James Youngman <[email protected]> Upgrade to gnulib version 86a37c05846ff3772afd1300f135866dd1d271c6. diff --git a/Makefile.am b/Makefile.am index 7e5d508..5ae14a1 100644 --- a/Makefile.am +++ b/Makefile.am @@ -3,7 +3,9 @@ AUTOMAKE_OPTIONS=gnits AM_CFLAGS = $(WARN_CFLAGS) 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 @@ -13,6 +15,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 9fc5875..f1c9ea6 100644 --- a/NEWS +++ b/NEWS @@ -26,6 +26,11 @@ unknown user or is missing. #25154: Allow compilation with C compilers that don't allow declarations to follow statements. +** Documentation Changes + +The file README-CVS has been renamed to README-hacking and improved. + + * Major changes in release 4.5.3, 2008-12-07 ** Bug Fixes 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 = [email protected] + + +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: + + [email protected], [email protected] + +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 [email protected] \ + --cc [email protected] /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
