Re: [PATCH] mm/vmscan: restore zone_reclaim_mode ABI

[Dave Hansen]

On 6/29/20 12:13 AM, Daniel Wagner wrote:
> On Fri, Jun 26, 2020 at 06:53:33AM -0700, Dave Hansen wrote:
>> Was there something else specifically in the documentation which you
>> think I've neglected?
> 
> The first paragraph explains how you ended up modifying the code. While
> I understand that you want to document the process, it wont help
> a reader in future. It doesn't add any intersting information at all.
> Just state what you're doing as first thing and explain why you are
> doing it after it.

I went back and looked at it to see what interesting information I think
the first paragraph conveys:

> I went to go add a new RECLAIM_* mode for the zone_reclaim_mode
> sysctl.

This conveys my motivation.  It relays that my discovery of the issue
was in the process of modifying the code, in contrast to it having being
found through observed pathological kernel behavior.

> Like a good kernel developer, I also went to go update the 
> documentation.

This takes the opportunity to throw a tiny bit of shade in the direction
of the other folks who modified the #define without updating the
documentation.  It also helps build the justification for the new
comment on top of the #defines.  I guess you can argue that this should
be struck from the changelog.  But, heck, it gave me a little chuckle
when read it just now.

> I noticed that the bits in the documentation didn't
> match the bits in the #defines.

This is the crux of the problem statement.  Can't get rid of this.

So, I guess I could pare the above down to simply:

	When modifying the zone_reclaim_mode sysctl documentation, I
	found through inspection that the bits in the documentation
	did not match the bits in the #defines.

That's certainly chuckle-free, and it would make my editor happy because
it's shorter and now he can sell another ad on the page.  Would you
prefer that form?

>>> I think the documentation update should not be part of this patch.
>>> This makes the back porting to stable more difficult.
>>
>> Really?  If a backporter doesn't care about documentation, I'd just
>> expect them to see the reject, ignore it, and move on with their life.
>> If they do, they'd want the code fix and the Documentation/ update in
>> the same patch so that they don't get disconnected.
> 
> I understood you are fixing a regression ingroduced by a previous change. In
> this case I would only fix the regression. Updating/improving the
> documentation is good, I just don't think it's necessary to back port it to
> stables trees along side the bug fix.

That's a question for the person doing the backport.  Attaching the two
things makes it the most likely that they will be given the best, most
complete information.

I've done my share of backports and I if it were me, I think I'd rather
have it this way.