[dpdk-dev] expectations on maintainer's review

Bruce Richardson bruce.richardson at intel.com
Wed Mar 9 15:15:04 CET 2016


On Wed, Mar 09, 2016 at 12:26:58PM +0100, Thomas Monjalon wrote:
> I've changed the title for this discussion.
> 
> 2016-03-09 11:01, Bruce Richardson:
> [snip comments about minor issue in release notes]
> 
> > Your question, though, does bring up the issue of scope and reviews again. I, as
> > committer, spend a lot of time tweaking commit messages, sanity checking
> > patches for compilation errors under various settings, and running checkpatch
> > etc. before applying them. However, IMHO it is up to the maintainers of the
> > various subsystems to enforce proper documentation in the patches submitted.
> > The maintainers are the primary gatekeepers here, and I, for one, don't want to
> > end up having to review all patches in detail before I apply them - otherwise
> > we'll be limited to a very small number of driver patches per release :)
> 
> Yes that's a problem.
> 
> > In this case, if the submitter of the patch and the maintainer of the driver in
> > question are happy with the documentation, then who am I to go querying that. :-)
> > 
> > Having committers do full review on apply will only have two possible effects:
> > 1. make the maintainers less conscientious about their job, since they know the
> >   committers will catch any real bugs or issues on apply
> 
> Yes we need maintainers to be conscientious on every parts of the patches.

Definite +1

> One problem about the release notes and doc, is that not a lot of maintainers
> have the "english skills".
> Note that it would be easier if we would allow to write in Irish, Chinese or
> French languages ;)
> Unfortunately we took the constraints of writing in C and English.
> 

Yes, language is a good point, and I'm ok with helping to clean up grammar and 
minor language issues e.g. the one word correction I suggested at the start of
this discussion. For the scope of the text, and whether it contains enough
information, I would tend to push that responsibility back on the maintainer
though.


> > 2. cause a lot of problems for submitters as they see a lot of issues being
> >   flagged at the last minute by committers, when they thought their patch was
> >   safely acked and ready for commit for some time.
> > 
> > We certainly see lots of the second issue occurring right now, I believe - [I'm
> > obvously not going to comment on the former :-)]
> > 
> > I'd be very much in favour of having a rule that once a patch is acked by a
> > maintainer, then it must be applied. We may suffer a bit from slightly lower
> > quality patches getting applied, but the speed of applying patches should
> > increase, and the patch contents can always be fixed by subsequent patches later.
> > [Unlike commit message which can't be fixed later without rewriting git history]
> > In this case, I feel that phrase "the perfect is the enemy of the good" applies.
> > https://en.wikipedia.org/wiki/Perfect_is_the_enemy_of_good
> 
> Yes but I don't think saying we are OK to decrease the quality is a good message.
> The reality is that people never rework what was been committed.

Yes, point taken.

> That's why we must be very careful on API and documentation.
> About the release notes, decreasing its quality mean we don't care wether it is
> read and understood. So maybe we can shrink it to less details and have only a
> title with a git/author reference.

I don't think I agree with that. I think the doc should be readable independently
of having the git repo.

> 
> > Just my 2c on this. I'm sure you have a different view, Thomas, so it's probably
> > a discussion worth having.
> 
> Thanks for bringing the discussion.

Indeed. So I would summarise this as:
* an ask to the maintainers to pay increased attention to documentation side of
patches when reviewing and acking.
* on my end, I will do some doc reviews as part of applying commits, but on a
best-effort basis. The primary responsibility is with the maintainers to ensure
documentation quantity before patch application stage.

Does that seem reasonable?

Regards,
/Bruce


More information about the dev mailing list