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

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

[John McNamara]

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(-)

diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst
index fabddbe..3b5746b 100644
--- a/doc/guides/contributing/patches.rst
+++ b/doc/guides/contributing/patches.rst
@@ -12,7 +12,7 @@ The rationale for many of the DPDK guidelines is explained in greater detail in
 
 
 The DPDK Development Process
------------------------------
+----------------------------
 
 The DPDK development process has the following features:
 
@@ -21,13 +21,9 @@ The DPDK development process has the following features:
 * There are maintainers for hierarchical components.
 * Patches are reviewed publicly on the mailing list.
 * Successfully reviewed patches are merged to the repository.
-
-|
-
-* There are main repository ``dpdk`` and sub-repositories ``dpdk-next-*``.
-* A patch should be sent for its target repository. Like net drivers should be on top of dpdk-next-net repository.
-* All sub-repositories are merged into main repository for -rc1 and -rc2 versions of the release.
-* After -rc2 release all patches should target main repository.
+* Patches should be sent to the target repository or sub-tree, see below.
+* All sub-repositories are merged into main repository for ``-rc1`` and ``-rc2`` versions of the release.
+* After the ``-rc2`` release all patches should target the main repository.
 
 The mailing list for DPDK development is `dev@dpdk.org <http://dpdk.org/ml/archives/dev/>`_.
 Contributors will need to `register for the mailing list <http://dpdk.org/ml/listinfo/dev>`_ in order to submit patches.
@@ -37,6 +33,60 @@ The development process requires some familiarity with the ``git`` version contr
 Refer to the `Pro Git Book <http://www.git-scm.com/book/>`_ for further information.
 
 
+Maintainers and Sub-trees
+-------------------------
+
+The DPDK maintenance hierarchy is divided into a main repository ``dpdk`` and sub-repositories ``dpdk-next-*``.
+
+There are maintainers for the trees and for components within the tree.
+
+Trees and maintainers are listed in the ``MAINTAINERS`` file. For example::
+
+    Crypto Drivers
+    --------------
+    M: Some Name <some.name@email.com>
+    T: git://dpdk.org/next/dpdk-next-crypto
+
+    Intel AES-NI GCM PMD
+    M: Another Name <another.name@email.com>
+    F: drivers/crypto/aesni_gcm/
+    F: doc/guides/cryptodevs/aesni_gcm.rst
+
+Where:
+
+* ``M`` is a tree or component maintainer.
+* ``T`` is a repository tree.
+* ``F`` is a maintained file or directory.
+
+Additional details are given in the ``MAINTAINERS`` file.
+
+The role of the component maintainers is to:
+
+* 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.
+
+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.
+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.
+* Prepare the tree for integration.
+
+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.
+Disagreements on trees or maintainers can be brought to the Technical Steering Committee.
+
+Tree backup maintainers, when required, can be selected from the active tree maintainers.
+This can be agreed and coordinated by the tree maintainers.
+
+
 Getting the Source Code
 -----------------------
 
-- 
2.7.4

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

[Thomas Monjalon]

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

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

[Bruce Richardson]

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

[dpdk-dev] [PATCH v2] doc: add details of sub-trees and maintainers

[John McNamara]

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>
---

* V2: Added comments from mailing list.


 doc/guides/contributing/patches.rst | 72 ++++++++++++++++++++++++++++++++-----
 1 file changed, 64 insertions(+), 8 deletions(-)

diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst
index fabddbe..c7006c1 100644
--- a/doc/guides/contributing/patches.rst
+++ b/doc/guides/contributing/patches.rst
@@ -12,7 +12,7 @@ The rationale for many of the DPDK guidelines is explained in greater detail in
 
 
 The DPDK Development Process
------------------------------
+----------------------------
 
 The DPDK development process has the following features:
 
@@ -21,13 +21,9 @@ The DPDK development process has the following features:
 * There are maintainers for hierarchical components.
 * Patches are reviewed publicly on the mailing list.
 * Successfully reviewed patches are merged to the repository.
-
-|
-
-* There are main repository ``dpdk`` and sub-repositories ``dpdk-next-*``.
-* A patch should be sent for its target repository. Like net drivers should be on top of dpdk-next-net repository.
-* All sub-repositories are merged into main repository for -rc1 and -rc2 versions of the release.
-* After -rc2 release all patches should target main repository.
+* Patches should be sent to the target repository or sub-tree, see below.
+* All sub-repositories are merged into main repository for ``-rc1`` and ``-rc2`` versions of the release.
+* After the ``-rc2`` release all patches should target the main repository.
 
 The mailing list for DPDK development is `dev@dpdk.org <http://dpdk.org/ml/archives/dev/>`_.
 Contributors will need to `register for the mailing list <http://dpdk.org/ml/listinfo/dev>`_ in order to submit patches.
@@ -37,6 +33,66 @@ The development process requires some familiarity with the ``git`` version contr
 Refer to the `Pro Git Book <http://www.git-scm.com/book/>`_ for further information.
 
 
+Maintainers and Sub-trees
+-------------------------
+
+The DPDK maintenance hierarchy is divided into a main repository ``dpdk`` and sub-repositories ``dpdk-next-*``.
+
+There are maintainers for the trees and for components within the tree.
+
+Trees and maintainers are listed in the ``MAINTAINERS`` file. For example::
+
+    Crypto Drivers
+    --------------
+    M: Some Name <some.name@email.com>
+    B: Another Name <another.name@email.com>
+    T: git://dpdk.org/next/dpdk-next-crypto
+
+    Intel AES-NI GCM PMD
+    M: Some One <some.one@email.com>
+    F: drivers/crypto/aesni_gcm/
+    F: doc/guides/cryptodevs/aesni_gcm.rst
+
+Where:
+
+* ``M`` is a tree or component maintainer.
+* ``B`` is a tree backup maintainer.
+* ``T`` is a repository tree.
+* ``F`` is a maintained file or directory.
+
+Additional details are given in the ``MAINTAINERS`` file.
+
+The role of the component maintainers is to:
+
+* Review patches for the component or delegate the review.
+  The review should be done, ideally, within 1 week of submission to the mailing list.
+* Add an ``acked-by`` to patches, or patchsets, that are ready for committing to a tree.
+
+Component maintainers can be added or removed by submitting a patch to the ``MAINTAINERS`` file.
+Maintainers should have demonstrated a reasonable level of contributions or reviews to the component area.
+The maintainer 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 patches that have been reviewed by component maintainers and/or other contributors.
+  The tree maintainer should determine if patches have been reviewed sufficiently.
+* Ensure that patches are reviewed in a timely manner.
+* Prepare the tree for integration.
+* Ensure that there is a designated back-up maintainer and coordinate a handover for periods where the
+  tree maintainer can't perform their role.
+
+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.
+The maintainer should be confirmed by an ``ack`` from an existing tree maintainer.
+Disagreements on trees or maintainers can be brought to the Technical Board.
+
+The backup maintainer for the master tree should be selected from the existing sub-tree maintainers from the project.
+The backup maintainer for a sub-tree should be selected from among the component maintainers within that sub-tree.
+
+
 Getting the Source Code
 -----------------------
 
-- 
2.7.4

Re: [dpdk-dev] [PATCH v2] doc: add details of sub-trees and maintainers

[Thomas Monjalon]

2016-12-16 17:50, John McNamara:
> 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>

Applied, thanks