[dpdk-dev,v1] doc: add details of sub-trees and maintainers

  Add a new section to the Code Contributors Guide to outline
the roles of tree and component maintainers and how they
can be added and removed.

Signed-off-by: John McNamara <john.mcnamara@intel.com>
---
 doc/guides/contributing/patches.rst | 66 ++++++++++++++++++++++++++++++++-----
 1 file changed, 58 insertions(+), 8 deletions(-)
  

Thanks for documenting the process, John.

2016-12-02 16:44, John McNamara:
> +The role of the component maintainers is to:
> +

I would add:
* Coordinate how improvements and fixes are done.

> +* Review patches for the component or delegate the review.
> +  This should be done, ideally, within 1-2 weeks of submission to the mailing list.
> +* Add an ``acked-by`` to patches, or patchsets, that they agree are ready for committing to a tree.

I do not understand "that they agree are ready"

> +Component maintainers can be added or removed by submitting a patch to the ``MAINTAINERS`` file.
> +Maintainers should have demonstrated a reasonable level of contributions to the component area or to a similar area.

I suggest "a reasonable level of contributions or reviews for the component area".

> +This should be confirmed by an ``ack`` from an established contributor.
> +There can be more than one component maintainer if desired.
> +
> +The role of the tree maintainers is to:
> +
> +* Maintain the overall quality of their tree.
> +  This can entail additional review, compilation checks or other tests deemed necessary by the maintainer.
> +* Commit reviewed patches.

We need to explain that a tree maintainer rely on component maintainers
and also on any contributor doing a review. However he does not give
the same credit to everyone. It is a matter of trust.
When a not (yet) trusted contributor gives an opinion, it may need
more checks or opinions.

> +* Prepare the tree for integration.

They are responsibles of the pace, giving time for reviews and tests while releasing in time.

> +Tree maintainers can be added or removed by submitting a patch to the ``MAINTAINERS`` file.
> +The proposer should justify the need for a new sub-tree and should have demonstrated a sufficient level of contributions in the area or to a similar area.
> +This should be confirmed by 3 ``acks`` from established contributors.

In practice, people do not give acks because it is obvious.
I think there is no need to add the 3 acks rule because of the line below.

> +Disagreements on trees or maintainers can be brought to the Technical Steering Committee.

Its name is still the "Technical Board".

> +Tree backup maintainers, when required, can be selected from the active tree maintainers.
> +This can be agreed and coordinated by the tree maintainers.

OK, thanks
  

On Tue, Dec 06, 2016 at 06:32:37PM +0100, Thomas Monjalon wrote:
> Thanks for documenting the process, John.
> 
> 2016-12-02 16:44, John McNamara:
> > +The role of the component maintainers is to:
> > +
> 
> I would add:
> * Coordinate how improvements and fixes are done.
> 
> > +* Review patches for the component or delegate the review.
> > +  This should be done, ideally, within 1-2 weeks of submission to the mailing list.
> > +* Add an ``acked-by`` to patches, or patchsets, that they agree are ready for committing to a tree.
> 
> I do not understand "that they agree are ready"
> 
> > +Component maintainers can be added or removed by submitting a patch to the ``MAINTAINERS`` file.
> > +Maintainers should have demonstrated a reasonable level of contributions to the component area or to a similar area.
> 
> I suggest "a reasonable level of contributions or reviews for the component area".
> 
> > +This should be confirmed by an ``ack`` from an established contributor.
> > +There can be more than one component maintainer if desired.
> > +
> > +The role of the tree maintainers is to:
> > +
> > +* Maintain the overall quality of their tree.
> > +  This can entail additional review, compilation checks or other tests deemed necessary by the maintainer.
> > +* Commit reviewed patches.
> 
> We need to explain that a tree maintainer rely on component maintainers
> and also on any contributor doing a review. However he does not give
> the same credit to everyone. It is a matter of trust.
> When a not (yet) trusted contributor gives an opinion, it may need
> more checks or opinions.
> 
> > +* Prepare the tree for integration.
> 
> They are responsibles of the pace, giving time for reviews and tests while releasing in time.
> 
> > +Tree maintainers can be added or removed by submitting a patch to the ``MAINTAINERS`` file.
> > +The proposer should justify the need for a new sub-tree and should have demonstrated a sufficient level of contributions in the area or to a similar area.
> > +This should be confirmed by 3 ``acks`` from established contributors.
> 
> In practice, people do not give acks because it is obvious.
> I think there is no need to add the 3 acks rule because of the line below.
> 

I would suggest that for new trees we just look for an ack from an
existing tree maintainer.

> > +Disagreements on trees or maintainers can be brought to the Technical Steering Committee.
> 
> Its name is still the "Technical Board".
> 
> > +Tree backup maintainers, when required, can be selected from the active tree maintainers.
> > +This can be agreed and coordinated by the tree maintainers.
> 
> OK, thanks

I would suggest a slightly different policy here - given that
maintainers of subtrees may not be fully familiar with the details of
other subtree. However, they should have a reasonable high-level view of
the project. Therefore I suggest:

* the backup maintainer for the master tree should be selected from the
  existing subtree maintainers from the project.
* the backup maintainer for a sub-tree should be selected from among the
  component maintainers within that subtree.

Having things this way would ensure that the maintenance of the master
tree is always done by someone familiar with maintaining trees, while
also at the same time having a way to allow others get familiar with
maintaining trees by taking a stint as backup sub-tree maintainer. It
also should ensure that e.g. the net tree committer is always someone
familiar with NIC PMDs.

/Bruce