Re: [PATCH] README-release improvements

[Gary V . Vaughan]

Hi Jim,

On 21 Oct 2011, at 15:17, Jim Meyering wrote:
> Gary V. Vaughan wrote:
>> I made these changes in gnulib-local/top/README-release while making
>> a start at leveraging the gnulib release machinery into GNU Libtool,
>> but they seem generally applicable too.
> 
> Thanks for the suggestions.
> However, it's not quite ready.

Thanks for the review.  Okay to push the much reduced patch at the
bottom?

>> Okay to push?
> 
> I'm glad you asked first.
> Please do that for every iteration with any file I maintain.

Not just your files, but everyone else's too! I would and have only ever
not asked first if I am working on a public personal branch or fixing an
obvious typo or obvious tiny bug.

> In the future, please post unmodified "git format-patch" output,
> precisely so that we can apply and test any such patch.

Of course! This patch was entirely text though with nothing at all
executable in it, so I thought I'd save myself the trouble of setting up
postfix on my new Lion installation on this occasion, because I already
had all the right files to hand.  On balance, I guess it is even easier
to git format-patch and paste that into my MUA, even though getting git
send-email to work after every OS upgrade is time consuming and annoying.

>> +* If you are a @PACKAGE@ maintainer, but have not yet registered your
>> +  gpg public key and (preferred) email address with the FSF, send an
>> +  email, preferably GPG-signed, to <address@hidden> that includes
>> +  the following:
>> +
>> +    (a) name of package(s) that you are the maintainer for, and your
>> +        preferred email address.
>> +
>> +    (b) an ASCII armored copy of your GnuPG key, as an attachment.
>> +       ("gpg --export -a YOUR_KEY_ID > mykey.asc" should give you
>> +       this.)
>> +
>> +  When you have received acknowledgement of your message, the proper GPG
>> +  keys will be registered on ftp-upload.gnu.org and only then will you be
>> +  authorized to upload files to the FSF ftp machines.
> 
> All of the above will be useful exactly once per person/package
> and then skipped forever after.  Also, that same information is
> already in the maintainer's guide.  Let's not duplicate it.

I added that to the libtool release checklist in 2004, because I was asked
for it a couple of times by new maintainers and it took me a while to find
it each time...

> If anything simply refer to that, e.g.,
> https://www.gnu.org/prep/maintain/html_node/Automated-Upload-Registration.html#Automated-Upload-Registration
> Though I am leery of adding even a one or two line note at
> the very top, when it's something that will be useful so seldom.

...but I'll put that URL in my gl/top/README-release.diff. Thanks.

>> +* If you do not have access to the mailing list administrative interface,
>> +  approach the list owners for the password.
> 
> This sentence is in the same vein.  Please omit it.

More from Ralf's under-specified:

Author: Ralf Wildenhues <address@hidden>
Date:   Mon Aug 8 06:47:42 2005 +0000

    * AUTHORS, HACKING: Updated.

I'll remove that too.  It is pretty obvious now you mention it.  Thanks.

>> Be sure to check the lists
>> +  (esp. address@hidden@) for outstanding bug reports also in the list of
>> +  pending moderation requests.
> 
> IMHO, the above is so obvious that it's not worth including.

Likewise.

> ...
>> -* Run ./configure && make maintainer-clean
>> -
> 
> Why do you want to remove the "make maintainer-clean"?
> I saw no justification, so maybe it's an accident.

Hmm... half and half. Here's the relevant bit of ChangeLog:

+       Don't try to run ./configure right after git pull incase files
+       that influence the bootstrap process have changed, move the
+       ./configure step to after running ./bootstrap.

As it stands (without this patch), README-release recommends:

  git checkout master
  git pull
  ./configure
  make maintainer-clean
  ./bootstrap
  
Running the (potentially) outdated configure, to build a (potentially)
outdated Makefile, which may very well rerun aclocal, automake, autoconf
etc just to call the maintainer-clean rule, and then blow it all away
in the next step with a bootstrap seems odd and torturous to me. Worse,
the next time you try to run make after the final bootstrap step, some
or all of the autotools will have to run again to regenerate the Makefile.

This patch reorders the steps thus:

  git checkout master
  git pull origin master  # don't try (perhaps fail) to pull other branches
  ./bootstrap             # rerun autotools explicitly on latest sources
  ./configure             # regenerate Makefile explicitly -"-   -"-

If you want to remove any file-droppings, you can use rm or git clean, or
make maintainer-clean as and when it fits the situation your working tree
is in. I didn't want to put an explicit git clean step in for fear of
deleting important non-tracked files from the tree of someone following
the steps without thinking hard enough before pressing RETURN.

> ...
>> -* Run bootstrap one last time.  This downloads any new translations:
>> +* Run "./bootstrap". This downloads any new translations.
> 
> Please leave two spaces after each sentence-ending ".".

Okay, sorry.  I've been trying really hard to break my silly habit of
automatically typing two spaces after every period[1], except in texinfo
input[2], partly because always counting spaces in patches becomes annoying
fairly quickly, and because double spaces after a period is widely
regarded as typographically bad. I've been meaning to write a syntax-check
rule to enforce the project convention, but didn't get around to that yet.

 [1]: http://www.mail-archive.com/address@hidden/msg06062.html
 [2]: http://www.mail-archive.com/address@hidden/msg06094.html

(which contain links to http://webword.com/reports/period.html and
http://en.wikipedia.org/wiki/Sentence_spacing)

>> * Send the announcement email message.
>> +  Address the email to address@hidden@@gnu.org' and
>> +  address@hidden' with the Reply-To header set to
>> +  address@hidden@@gnu.org'.  Stable releases should also be announced on
>> +  address@hidden'.
> 
> Please remove the above hunk.  First, it should not mention autotools.
> Though mainly, if the automatically-generated announcement does not include
> the headers you want, customize them via cfg.mk, using these variables:
> 
>    announcement_Cc_
>    announcement_mail_headers_

Ah, excellent, I didn't notice that when reading through the (giant!) maint.mk
on the first couple of passes. Done; thank you.

What's left is now rather small, but still addresses all those automated
reruns of various autotools:

--
readme-release: several release instructions improvements.

* README-release: Don't git pull all branches when only master
is needed for the release process.
Don't try to run ./configure right after git pull incase files
that influence the bootstrap process have changed, move the
./configure step to after running ./bootstrap.
Don't bootstrap "one last time"... it's the first time!
---
diff --git a/ChangeLog b/ChangeLog
index 25790a6..8b0f6a5 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2011-10-21  Gary V. Vaughan  <address@hidden>
+
+       readme-release: Don't git pull all branches when only master
+       is needed for the release process.
+       Don't try to run ./configure right after git pull incase files
+       that influence the bootstrap process have changed, move the
+       ./configure step to after running ./bootstrap.
+       Don't bootstrap "one last time"... it's the first time!
+
2011-10-19  Gary V. Vaughan  <address@hidden>

        maint.mk: Respect $(build_aux) in web-manual rule.
diff --git a/top/README-release b/top/README-release
index 0e1694d..f43b7ad 100755
--- a/top/README-release
+++ b/top/README-release
@@ -2,9 +2,7 @@
 
 * start from a clean, up-to-date git directory.
 
-    git checkout master; git pull
-
-* Run ./configure && make maintainer-clean
+    git checkout master; git pull origin master
 
 * Ensure that the desired versions of autoconf, automake, etc.
   are in your PATH.  See the buildreq list in bootstrap.conf for
@@ -18,12 +16,10 @@
 
       http://hydra.nixos.org/jobset/gnu/@address@hidden
 
-* Run bootstrap one last time.  This downloads any new translations:
-
-    ./bootstrap
+* Run "./bootstrap && ./configure".  This downloads any new translations.
 
 * Pre-release testing:
-  Ensure that make check syntax-check succeeds.
+  Ensure that "make check syntax-check" succeeds.
 
 * Run "make distcheck"


Cheers,
-- 
Gary V. Vaughan (gary AT gnu DOT org)