[RFC PATCH 0/3] HACKING cleanups

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

[RFC PATCH 0/3] HACKING cleanups

Eric Blake-3
Inspired by the recent application of Ben's patch.

I don't know if it is worth trying to omit mention of HACKING
from the generated ChangeLot. gitlog-to-changelog has an
--ignore-matching option that could be used to filter out
all commits that are git-only (in which case I would retitle
these commits to match that pattern, as well as modify Makefile.am
to specify the option).  But as far as I could tell, the
gitlog-to-changelog --amend option can't be used to specify
commits to completely ignore (and even if it could, how do
you ignore the very commit that is tweaking that file, given
that you don't know the commit id until after the tweak is
committed).

Eric Blake (3):
  maint: Merge HACKING and README-hacking
  maint: Tweak HACKING for generated ChangeLog
  maint: Allow amendments to git log when generating ChangeLog

 HACKING        | 153 +++++++++++++++++++++++++++++++++++++++++++++++++++------
 Makefile.am    |   6 ++-
 README-hacking | 139 ---------------------------------------------------
 3 files changed, 144 insertions(+), 154 deletions(-)
 delete mode 100644 README-hacking

--
2.9.3


Reply | Threaded
Open this post in threaded view
|

[PATCH 3/3] maint: Allow amendments to git log when generating ChangeLog

Eric Blake-3
Copied from Coreutils.  Note that git-log-fix does not yet
exist, and even when it does, it will not be part of the
tarball (since it only makes sense in the context of a git
checkout).

* Makefile.am (gen-ChangeLog): Allow for corrections.

Signed-off-by: Eric Blake <[hidden email]>
---
 Makefile.am | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/Makefile.am b/Makefile.am
index 296f2b5..b672d66 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -86,7 +86,11 @@ gen_start_date = 2012-01-15 18:00:00 UTC
 .PHONY: gen-ChangeLog
 gen-ChangeLog:
  if test -d $(top_srcdir)/.git; then \
-  $(top_srcdir)/build-aux/gitlog-to-changelog \
+  log_fix="$(srcdir)/build-aux/git-log-fix"; \
+  test -e "$$log_fix" \
+    && amend_git_log="--amend=$$log_fix" \
+    || amend_git_log=; \
+  $(top_srcdir)/build-aux/gitlog-to-changelog $$amend_git_log \
     --since='$(gen_start_date)' > $(distdir)/cl-t \
     && rm -f $(distdir)/ChangeLog \
     && mv $(distdir)/cl-t $(distdir)/ChangeLog; \
--
2.9.3


Reply | Threaded
Open this post in threaded view
|

[PATCH 2/3] maint: Tweak HACKING for generated ChangeLog

Eric Blake-3
In reply to this post by Eric Blake-3
Signed-off-by: Eric Blake <[hidden email]>
---
 HACKING | 39 +++++++++++++++++++++------------------
 1 file changed, 21 insertions(+), 18 deletions(-)

diff --git a/HACKING b/HACKING
index 07d7bcd..0f53bb8 100644
--- a/HACKING
+++ b/HACKING
@@ -33,16 +33,6 @@ generate the version string.  Therefore, we recommend:

 - Git 1.4.4+ <http://git.or.cz/>

-You may find it useful to install the git-merge-changelog merge driver:
-http://git.sv.gnu.org/gitweb/?p=gnulib.git;a=blob;f=lib/git-merge-changelog.c
-
-then add the following to .git/config or ~/.gitconfig:
-[merge "merge-changelog"]
- name = GNU ChangeLog merge driver
- driver = git-merge-changelog %O %A %B
-[diff "texinfo"]
- funcname = ^@node[\t ][\t ]*\\([^,][^,]*\\)
-
 Only building the initial full source tree will be a bit painful.
 Later, a plain `git pull && make' should be sufficient.

@@ -128,18 +118,32 @@ you'd use doc/Copyright/request-assign.future:

 * Administrivia

+** The ChangeLog is generated from git commit comments.
+
+Your commit log should always start with a one-line summary, the second
+line should be blank, and the remaining lines are usually ChangeLog-style
+entries for all affected files.  However, it's fine -- even recommended --
+to write a few lines of prose describing the change, when the summary
+and ChangeLog entries don't give enough of the big picture.  Omit the
+leading TABs that you're used to seeing in a "real" ChangeLog file, but
+keep the maximum line length at 72 or smaller, so that the generated
+ChangeLog lines, each with its leading TAB, will not exceed 80 columns.
+As for the ChangeLog-style content, please follow these guidelines:
+
+  http://www.gnu.org/software/guile/changelogs/guile-changelogs_3.html
+
 ** If you incorporate a change from somebody on the net:
 First, if it is a large change, you must make sure they have signed
 the appropriate paperwork.  Second, be sure to add their name and
 email address to THANKS.

 ** Test fixes
-If a change fixes a test, mention the test in the ChangeLog entry.
-To this end, the Autotest-mode is handy.
+If a change fixes a test, mention the test in the commit log. To this
+end, the Autotest-mode is handy.

 ** Bug reports
-If somebody reports a new bug, mention their name in the ChangeLog
-entry and in the test case you write.  Put them into THANKS.
+If somebody reports a new bug, mention their name in the commit log,
+and put them into THANKS.

 The correct response to most actual bugs is to write a new test case
 which demonstrates the bug.  Then fix the bug, re-run the test suite,
@@ -224,10 +228,9 @@ should check the results before committing them in git.

 ** Set the version number
 Update the version number in NEWS (with version, date, and release
-type) and ChangeLog, and mention in README whether the release is
-stable.  Make sure all changes are committed, then run `git tag -s -m
-<version> -u <gpg_key> v<version>'.  Do not push anything upstream at
-this point.
+type), and mention in README whether the release is stable.  Make sure
+all changes are committed, then run `git tag -s -m <version> -u
+<gpg_key> v<version>'.  Do not push anything upstream at this point.

 ** Update configure
 As much as possible, make sure to release an Autoconf that uses
--
2.9.3


Reply | Threaded
Open this post in threaded view
|

[PATCH 1/3] maint: Merge HACKING and README-hacking

Eric Blake-3
In reply to this post by Eric Blake-3
It makes no sense to have two files that describe things that
only apply to a git checkout, when only one will do.

Signed-off-by: Eric Blake <[hidden email]>
---
 HACKING        | 134 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 README-hacking | 139 ---------------------------------------------------------
 2 files changed, 128 insertions(+), 145 deletions(-)
 delete mode 100644 README-hacking

diff --git a/HACKING b/HACKING
index 7ce33d2..07d7bcd 100644
--- a/HACKING
+++ b/HACKING
@@ -1,10 +1,130 @@
 -*- outline -*-

-This file attempts to describe the maintainer-specific notes to follow
-when hacking Autoconf.  Don't put this file into the distribution.
-Don't mention it in the ChangeLog.  You may want to first see
-README-hacking for more general rules on building Autoconf from
-checked-out sources.
+These notes intend to help people working on the checked-out sources,
+including maintainer-specific notes for making a release tarball.
+These requirements do not apply when building from a distribution
+tarball.  Don't put this file into the distribution.
+
+* Requirements
+
+We've opted to keep only the highest-level sources in the GIT repository.
+This eases our maintenance burden, (fewer merges etc.), but imposes more
+requirements on anyone wishing to build from the just-checked-out sources.
+For example, you have to use recent stable versions of the maintainer
+tools we depend upon, including:
+
+- Autoconf 2.60+ <http://www.gnu.org/software/autoconf/>
+- Automake 1.10+ <http://www.gnu.org/software/automake/>
+- Help2man 1.29+ <http://www.gnu.org/software/help2man/>
+- M4 1.4.6+ <http://www.gnu.org/software/m4/>
+- Perl 5.006+ <http://www.cpan.org/>
+- Texinfo 4.8+ <http://www.gnu.org/software/texinfo/>
+
+The following are useful as well, if you want to be able to run commands
+like "make dist-lzma" or "make distcheck":
+
+- Gzip <http://www.gnu.org/software/gzip/>
+- Tar <http://www.gnu.org/software/tar/>
+- LZMA Utils 4.32+ <http://tukaani.org/lzma/>
+
+Although we try to keep the CVS mirror of the git repository usable,
+some of the tests in the testsuite will fail if git was not used to
+generate the version string.  Therefore, we recommend:
+
+- Git 1.4.4+ <http://git.or.cz/>
+
+You may find it useful to install the git-merge-changelog merge driver:
+http://git.sv.gnu.org/gitweb/?p=gnulib.git;a=blob;f=lib/git-merge-changelog.c
+
+then add the following to .git/config or ~/.gitconfig:
+[merge "merge-changelog"]
+ name = GNU ChangeLog merge driver
+ driver = git-merge-changelog %O %A %B
+[diff "texinfo"]
+ funcname = ^@node[\t ][\t ]*\\([^,][^,]*\\)
+
+Only building the initial full source tree will be a bit painful.
+Later, a plain `git pull && make' should be sufficient.
+
+If you want to test Autoconf on a machine without git, it may be
+easier to first bootstrap Autoconf on a different machine with git,
+run `make dist', and copy the tarball to the machine under test.  It
+should always be possible to create a self-contained tarball which
+does not rely on the bootstrap-only tools.
+
+* First GIT checkout
+
+You can get an anonymous copy of the source repository using any one
+of these three methods, although the CVS mirror is less tested:
+
+  $ git clone git://git.sv.gnu.org/autoconf
+  $ git clone http://git.sv.gnu.org/r/autoconf.git
+  $ cvs -d:pserver:[hidden email]:/srv/git/autoconf.git \
+      co -d autoconf HEAD
+
+If you have a Savannah user name and commit rights to the Autoconf
+project, you should use this instead:
+
+  $ git clone <username>@git.sv.gnu.org:/srv/git/autoconf.git
+
+The next step is to generate files like configure and Makefile.in:
+
+  $ cd autoconf
+  $ autoreconf -vi
+
+Since we're building autoconf itself, and its tests are picky, the
+following procedure includes an extra step to ensure that some
+generated files are regenerated using the tools just built by "make"
+(if you use GNU make, the file GNUmakefile sets PATH for you):
+
+  $ ./configure
+  $ make
+  $ ( PATH=`pwd`/tests:$PATH; autoreconf -vi )
+  $ make check
+
+At this point, there should be no difference between your local copy,
+and the GIT master copy:
+
+  $ git diff
+
+should output no difference.
+
+The testsuite is run by 'make check'.  You may find it useful to run a
+subset of the testsuite; for example, all tests with the 'm4sugar'
+keyword as well as test 10:
+
+  $ make check TESTSUITEFLAGS='10 -k m4sugar'
+
+You can pass options to configure scripts invoked by the testsuite by
+setting the configure_options variable:
+
+  $ make check TESTSUITEFLAGS='configure_options="CC=gcc-2.95"'
+
+* Submitting patches
+
+All patches should be submitted to <[hidden email]> for
+review, in context or unified diff format against the latest sources.
+In most cases, a patch should include a test case, to ensure that
+regressions do not creep back in.  Remember to add documentation and a
+NEWS entry for anything that is visible to the user.
+
+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 autoconf work,
+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

 * Administrivia

@@ -157,9 +277,11 @@ Update the Free Software Directory: browse to:
 and send an email to <[hidden email]> mentioning any content
 that needs to be updated.

+Enjoy!
+
 -----

-Copyright (C) 2002, 2008-2016 Free Software Foundation, Inc.
+Copyright (C) 2002-2016 Free Software Foundation, Inc.

 Copying and distribution of this file, with or without modification,
 are permitted in any medium without royalty provided the copyright
diff --git a/README-hacking b/README-hacking
deleted file mode 100644
index ec2e215..0000000
--- a/README-hacking
+++ /dev/null
@@ -1,139 +0,0 @@
--*- outline -*-
-
-These notes intend to help people working on the checked-out sources.
-These requirements do not apply when building from a distribution
-tarball.  Don't put this file into the distribution.  Don't mention it
-in the ChangeLog.  You may want to also see HACKING for
-maintainer-specific rules.
-
-* Requirements
-
-We've opted to keep only the highest-level sources in the GIT repository.
-This eases our maintenance burden, (fewer merges etc.), but imposes more
-requirements on anyone wishing to build from the just-checked-out sources.
-For example, you have to use recent stable versions of the maintainer
-tools we depend upon, including:
-
-- Autoconf 2.60+ <http://www.gnu.org/software/autoconf/>
-- Automake 1.10+ <http://www.gnu.org/software/automake/>
-- Help2man 1.29+ <http://www.gnu.org/software/help2man/>
-- M4 1.4.6+ <http://www.gnu.org/software/m4/>
-- Perl 5.006+ <http://www.cpan.org/>
-- Texinfo 4.8+ <http://www.gnu.org/software/texinfo/>
-
-The following are useful as well, if you want to be able to run commands
-like "make dist-lzma" or "make distcheck":
-
-- Gzip <http://www.gnu.org/software/gzip/>
-- Tar <http://www.gnu.org/software/tar/>
-- LZMA Utils 4.32+ <http://tukaani.org/lzma/>
-
-Although we try to keep the CVS mirror of the git repository usable,
-some of the tests in the testsuite will fail if git was not used to
-generate the version string.  Therefore, we recommend:
-
-- Git 1.4.4+ <http://git.or.cz/>
-
-You may find it useful to install the git-merge-changelog merge driver:
-http://git.sv.gnu.org/gitweb/?p=gnulib.git;a=blob;f=lib/git-merge-changelog.c
-
-then add the following to .git/config or ~/.gitconfig:
-[merge "merge-changelog"]
- name = GNU ChangeLog merge driver
- driver = git-merge-changelog %O %A %B
-[diff "texinfo"]
- funcname = ^@node[\t ][\t ]*\\([^,][^,]*\\)
-
-Only building the initial full source tree will be a bit painful.
-Later, a plain `git pull && make' should be sufficient.
-
-If you want to test Autoconf on a machine without git, it may be
-easier to first bootstrap Autoconf on a different machine with git,
-run `make dist', and copy the tarball to the machine under test.  It
-should always be possible to create a self-contained tarball which
-does not rely on the bootstrap-only tools.
-
-* First GIT checkout
-
-You can get an anonymous copy of the source repository using any one
-of these three methods, although the CVS mirror is less tested:
-
-  $ git clone git://git.sv.gnu.org/autoconf
-  $ git clone http://git.sv.gnu.org/r/autoconf.git
-  $ cvs -d:pserver:[hidden email]:/srv/git/autoconf.git \
-      co -d autoconf HEAD
-
-If you have a Savannah user name and commit rights to the Autoconf
-project, you should use this instead:
-
-  $ git clone <username>@git.sv.gnu.org:/srv/git/autoconf.git
-
-The next step is to generate files like configure and Makefile.in:
-
-  $ cd autoconf
-  $ autoreconf -vi
-
-Since we're building autoconf itself, and its tests are picky, the
-following procedure includes an extra step to ensure that some
-generated files are regenerated using the tools just built by "make"
-(if you use GNU make, the file GNUmakefile sets PATH for you):
-
-  $ ./configure
-  $ make
-  $ ( PATH=`pwd`/tests:$PATH; autoreconf -vi )
-  $ make check
-
-At this point, there should be no difference between your local copy,
-and the GIT master copy:
-
-  $ git diff
-
-should output no difference.
-
-The testsuite is run by 'make check'.  You may find it useful to run a
-subset of the testsuite; for example, all tests with the 'm4sugar'
-keyword as well as test 10:
-
-  $ make check TESTSUITEFLAGS='10 -k m4sugar'
-
-You can pass options to configure scripts invoked by the testsuite by
-setting the configure_options variable:
-
-  $ make check TESTSUITEFLAGS='configure_options="CC=gcc-2.95"'
-
-* Submitting patches
-
-All patches should be submitted to <[hidden email]> for
-review, in context or unified diff format against the latest sources.
-In most cases, a patch should include a test case, to ensure that
-regressions do not creep back in.  Remember to add documentation and a
-NEWS entry for anything that is visible to the user.
-
-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 autoconf work,
-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
-
-Enjoy!
-
------
-
-Copyright (C) 2002-2016 Free Software Foundation, Inc.
-
-Copying and distribution of this file, with or without modification,
-are permitted in any medium without royalty provided the copyright
-notice and this notice are preserved.  This file is offered as-is,
-without warranty of any kind.
--
2.9.3


Reply | Threaded
Open this post in threaded view
|

Re: [PATCH 3/3] maint: Allow amendments to git log when generating ChangeLog

Eric Blake-3
In reply to this post by Eric Blake-3
[adding coreutils]

On 12/22/2016 03:36 PM, Eric Blake wrote:

> Copied from Coreutils.  Note that git-log-fix does not yet
> exist, and even when it does, it will not be part of the
> tarball (since it only makes sense in the context of a git
> checkout).
>
> * Makefile.am (gen-ChangeLog): Allow for corrections.
>
> Signed-off-by: Eric Blake <[hidden email]>
> ---
>  Makefile.am | 6 +++++-
>  1 file changed, 5 insertions(+), 1 deletion(-)
>
> diff --git a/Makefile.am b/Makefile.am
> index 296f2b5..b672d66 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -86,7 +86,11 @@ gen_start_date = 2012-01-15 18:00:00 UTC
>  .PHONY: gen-ChangeLog
>  gen-ChangeLog:
>   if test -d $(top_srcdir)/.git; then \
> -  $(top_srcdir)/build-aux/gitlog-to-changelog \
> +  log_fix="$(srcdir)/build-aux/git-log-fix"; \
> +  test -e "$$log_fix" \
> +    && amend_git_log="--amend=$$log_fix" \
> +    || amend_git_log=; \
Note that Autoconf's HACKING file starts by pointing out that it applies
only to a git checkout, and therefore HACKING should NOT be included in
the distribution tarball.  Likewise, any git-log-fix file should not be
part of the tarball (it only makes sense to run the gen-ChangeLog rule
if you are in a git checkout).

Since I just copied autoconf's rule from coreutils, I'm wondering if
coreutils has a plan in place for handling commits that affect only git,
such as committing a change to git-log-fix (right now, coreutils'
git-log-fix has just four revisions - and sadly all of those show up in
the generated ChangeLog, even when that commit changes nothing in the
tarball itself, other than possibly an inter-release version string).

Maybe it's worth improving the gen-ChangeLog rule to use
'--ignore-matching="^git-only:"', so that you can tag all further edits
to git-log-fix as git-only: and automatically exclude those commits from
further muddying the generated ChangeLog.  Thoughts?


> +  $(top_srcdir)/build-aux/gitlog-to-changelog $$amend_git_log \
>      --since='$(gen_start_date)' > $(distdir)/cl-t \
>      && rm -f $(distdir)/ChangeLog \
>      && mv $(distdir)/cl-t $(distdir)/ChangeLog; \
>

--
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


signature.asc (617 bytes) Download Attachment