Re: who needs script `update-patch-version`?

[Jonas Hahnfeld]

Am Montag, dem 01.02.2021 um 16:06 +0100 schrieb Werner LEMBERG:
> > > Unfortunately, this is next to impossible since there are so many
> > > changes.  I will provide a PDF that holds the changed pages so
> > > that
> > > you and others can simply read what's written there, comparing it
> > > with the current version of the Contributor guide if necessary.
> > 
> > It was this condition (to provide small incremental changes) that
> > made me abandon editing the docs many years ago.  At the time I was
> > part-way through a major reorganisation of 2.1 Vocal Music which I
> > had to abandon as it was simply impossible to do it incrementally.
> > Since then the docs have virtually stagnated.  Hope you're able to
> > work this out better than I was able to do, Werner.
> 
> Well, I revise the stuff, I don't rewrite it, so it's definitely
> easier, I guess.  The main thing is that these extra steps take a
> significant amount of time, which I think are not really justified
> for documentation changes (in contrast to code changes) and could be
> invested into more useful things.

Let me disagree: Documentation (in particular targeting users for a
program like LilyPond) should be reviewed like code. And if you're not
willing to put effort and time into preparing the changes, why do you
expect others to spend their time on reviewing?

> In particular, for what I'm going to do, the command
> 
>   git diff --word-diff-regex=. --word-diff=color ...
> 
> makes it almost trivial to see the changes, as shown in the
> attachment that holds the very first differences (you should use
> `less` or something similar to view it, ideally using a black
> background).

Seeing the difference is really not the point (although even that
becomes impossible for larger edits, cf !418), but that too many
changes at once make it harder than necessary.
Looking at these "very first differences", I would for example propose
that you commit all additions of @code, @var, @file, @q separately. It
forms a logical change ("Add texinfo markups" or something like that)
and as a reviewer I can easily scroll through that commit, agree with
the rationale and move on in probably 20 seconds. This is so much
easier than having to spend minutes on mentally disentangling this
change from a large commit, and comes at virtually no cost for you.

Jonas

signature.asc
Description: This is a digitally signed message part