[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH] Provide more detailed help on how to work with the git sources.
From: |
James Youngman |
Subject: |
[PATCH] Provide more detailed help on how to work with the git sources. |
Date: |
Thu, 5 Mar 2009 11:47:53 +0000 |
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 | 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 <address@hidden>
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 = 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