Re: [Ksummit-discuss] Maintainer's Summit Agenda Planning

[Josh Poimboeuf <jpoimboe@redhat.com>]

On Fri, Oct 06, 2017 at 09:56:44AM -0700, James Bottomley wrote:
> On Fri, 2017-10-06 at 10:32 -0600, Jonathan Corbet wrote:
> > On Fri, 6 Oct 2017 11:26:21 -0500
> > Josh Poimboeuf <jpoimboe@redhat.com> wrote:
> > 
> > > 
> > > I think it would be a good idea to have a Maintainer's Guide which
> > > tries to document a lot of this knowledge.  It would help new
> > > maintainers learn the ropes, and would also help drive consensus
> > > for maintainer's best practices.  It could document the typical
> > > processes of a maintainer, and policy guidelines like some of the
> > > above topics.
> > 
> > Strangely enough, this is a conversation that has been popping up in
> > other contexts too.  We may see an initial attempt before too long.
> > 
> > The tricky part, of course, is finding a way to document the
> > consensus on best practices without trying to "drive" it too hard.
> > 
> > My own thought is that a good starting place might be a "how to avoid
> > getting your pull request flamed" document, since there is some
> > semblance of a consensus there and it's a place where people often
> > make mistakes.
> 
> Actually, I'd argue this is the most arcane area.  Accepting a pull
> request represents the expression of a trust relationship and it's not
> entirely well documented how to form that.  The mechanics of what
> should be in it and how it should be split vary by puller.  For
> instance, Linus' requirements are reasonably well documented in git-
> request-pull, but other trees have varying requirements.  Why he might
> flame you varies from too many merge window patches in a non-merge
> window to to many merge points in the tree or "unclean" history.

Each thing you just said is a good example of something which should be
documented.  In fact I think each sentence could be expanded into a
paragraph or section in the document.

-- 
Josh