Re: [PATCH] README-release improvements

[Gary V. Vaughan]

Hi Jim,

On 22 Oct 2011, at 03:06, Jim Meyering wrote:
> Gary V. Vaughan wrote:
>> 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.
> 
> The above may be a little wasteful.  But it is reliable and turn-key.

No it isn't.  Imagine that the bootstrap process has changed upstream,
and that, for example, additional bootstrap steps are needed to fix a
bug in maintainer-clean.  The README-release mandated procedure tells
you to run the old maintainer-clean rule after potentially merging with
a new tree that has different requirements.  And you don't even rerun
bootstrap first to ensure that you get a Makefile with a matching
maintainer-clean rule.

It's very easy to think of a multitude of scenarios where it's not only
suboptimal but flat out wrong to recommend a full autoreconf run, and
a second additional configure run just to bring the tree back into a
semi consistent state that will even allow you to run maintainer-clean
at all.

If you want to clean the cruft out of your working directories before
starting the release process, you should do it before you change branches
and merge changes from upstream, using the Makefile that you already have
that is already in sync with the rest of your tree:

  make maintainer-clean
  git checkout master
  git pull origin master
  ./bootstrap
  ./configure

> If you know you've run "make maintainer-clean" recently, and you know
> that none of the tools that will regenerate key bits have changed (hard
> to know, though), then it's ok to skip.  It's not worth the risk, to me.
> I don't make releases frequently enough to worry about a few minutes of
> CPU time, even if it's only for a minimal thing like this.

If you know that you already ran maintainer-clean recently enough, or you
know that you are happy to git-clean the tree after switching branches
and merging in upstream changes, then you can save all the wasted time
watching the autotools rebuild themselves just in time to run a rule that
doesn't even match the new branch you switched to and upstream merges
you made.

If you didn't, then for goodness sake run the maintainer-clean either
before you switch branches and merge upstream changesets, or run it after
you bootstrapped the new tree into a self consistent state. It makes no
sense at all to run it in the middle when everything is in flux between
changing all the inputs (and potentially the bootstrap script) and running
the new bootstrap in the new tree.  Doubly so because you have to sit
around for 10 or 15 minutes watching it rebuild a ton of files to get to
the point where you run the inconsistent maintainer-clean and then delete
them all when it's finished.  The fact that they need to be deleted and
rebuilt properly later on is a big clue that something is wrong with the
files at this point.

> I want a list of rules that I can follow with a minimum of thinking.

Me too, and having to think about the differences between the files laying
around because of the tree I just switched from, and the upstream changes
I'm merging, compared to what the maintainer-clean from  the half-synced
pre-bootstrap working directory will do is not that.

> Ideally it would be scripted, but we can save that for another day.

Agreed.

>> 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
> 
> Using git clean here is not an option.

Recommending it as a hard and fast step is very bad.  But if you know what
you're doing, it's at least 10 minutes faster.

> And manually running "rm" is obviously not maintainable.
> Add a new gnulib module and you may easily pull in rules to
> generate files that only "make maintainer-clean" will remove.

Delete a gnulib module, (or switch to a branch with one less module) and you
may easily need additional rules from the old tree to maintainer-clean your
working directory correctly... but you remove the chance to do it right by
putting the maintainer-clean call in exactly the wrong position in the
running order.

> If you really dislike burning the extra CPU cycles, patch
> the procedure for your projects.

I don't care about the CPU cycles, they are cheap enough... but I'd rather
save everyone else who follows these instructions blindly from wasting 10
or 15 minutes of their life every time they release a project.  That quickly
adds up to a lot of man hours that could be spent improving the GNU project
instead.

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