From mboxrd@z Thu Jan 1 00:00:00 1970 From: Bruce Richardson Subject: Re: expectations on maintainer's review Date: Wed, 9 Mar 2016 14:15:04 +0000 Message-ID: <20160309141502.GA15892@bricha3-MOBL3> References: <1456469514-9103-1-git-send-email-jingjing.wu@intel.com> <3177758.3DUFdx3GZH@xps13> <20160309110138.GB16076@bricha3-MOBL3> <2577394.tDVninKuVb@xps13> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Cc: dev@dpdk.org To: Thomas Monjalon Return-path: Received: from mga01.intel.com (mga01.intel.com [192.55.52.88]) by dpdk.org (Postfix) with ESMTP id CB1102B96 for ; Wed, 9 Mar 2016 15:15:11 +0100 (CET) Content-Disposition: inline In-Reply-To: <2577394.tDVninKuVb@xps13> List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" 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