Subject: Re: [PATCH v3 02/34] fsmonitor--daemon: man page

From: Felipe Contreras <[email-masked]>
Date: Fri, 16 Jul 2021 12:04:22 -0500

Johannes Schindelin wrote:
> On Tue, 13 Jul 2021, Ævar Arnfjörð Bjarmason wrote:
> 
> > [snip Ævar's suggestion to populate the manual page incrementally,
> > interspersed with the commits that finalize implementing the respective
> > functionality]
> >
> > I suggested this because I think it's much easier to read patches that
> > are larger because they incrementally update docs or tests along with
> > code, than smaller ones that are e.g. "add docs" followed by
> > incrementally modifying the code.
> 
> My experience is the exact opposite of yours: shorter patches are easier
> to read.

It depends.

> > That's because you can consider those atomically.
> 
> No, in a patch series you cannot consider any patch completely atomically.
> Just like you don't consider any paragraph in any well-written book out of
> context.

But you do not put every sentence in a paragraph.

Sometimes a paragraph can contain a single sentence, or a single word
even. But other times to properly read what is being tried to say you
need a pretty big paragraph.

> This all sounds like we're truly falling into the trap of ignoring the
> rule that the perfect is the enemy of the good.

Have you established that this is good enough?

-- 
Felipe Contreras