From cfc3d83161700a1dc14645c644c7b36142dd15cd Mon Sep 17 00:00:00 2001 From: Christopher Ferris Date: Thu, 27 Sep 2018 11:35:45 -0400 Subject: [PATCH] FAB-12199 update Contributing Guide added section on project governance to make clearer how we operate. Feedback welcomed. Change-Id: I044308f4b040d99577f80729d9af377531e206ee Signed-off-by: Christopher Ferris --- docs/source/CONTRIBUTING.rst | 216 +++++++++++++++++++++-------------- 1 file changed, 129 insertions(+), 87 deletions(-) diff --git a/docs/source/CONTRIBUTING.rst b/docs/source/CONTRIBUTING.rst index e044b044168..b353490cfce 100644 --- a/docs/source/CONTRIBUTING.rst +++ b/docs/source/CONTRIBUTING.rst @@ -8,23 +8,112 @@ First things first, please review the Hyperledger `Code of Conduct `__ before participating. It is important that we keep things civil. -.. toctree:: - :maxdepth: 1 +Project Governance +------------------ - MAINTAINERS - jira_navigation - dev-setup/devenv - dev-setup/build - Gerrit/lf-account - Gerrit/gerrit - Gerrit/changes - Gerrit/reviewing - Gerrit/best-practices - testing - Style-guides/go-style +Hyperledger Fabric is managed under an open governance model as described in +our `charter `__. Projects and +sub-projects are lead by a set of maintainers. New sub-projects can +designate an initial set of maintainers that will be approved by the +top-level project's existing maintainers when the project is first +approved. + +Maintainers +~~~~~~~~~~~ + +The Fabric project is lead by the project's top level :doc:`maintainers `. +The maintainers are responsible for reviewing and merging all patches submitted +for review, and they guide the overall technical direction of the project within +the guidelines established by the Hyperledger Technical Steering Committee (TSC). + +Becoming a maintainer +~~~~~~~~~~~~~~~~~~~~~ + +The project's maintainers will, from time-to-time, consider +adding or removing a maintainer. An existing maintainer can submit a +change set to the :doc:`MAINTAINERS.rst ` file. A nominated +Contributor may become a Maintainer by a majority approval of the proposal +by the existing Maintainers. Once approved, the change set is then merged +and the individual is added to (or alternatively, removed from) the maintainers +group. Maintainers may be removed by explicit resignation, for prolonged +inactivity (3 or more months), or for some infraction of the `code of conduct +`__ +or by consistently demonstrating poor judgement. A maintainer removed for +inactivity should be restored following a sustained resumption of contributions +and reviews (a month or more) demonstrating a renewed commitment to the project. + +Release cadence +~~~~~~~~~~~~~~~ + +The Fabric maintainers have settled on a quarterly (approximately) release +cadence (see `releases `__). +We are also actively considering adopting an LTS (long term support) release +process, though the details of this are still being worked out by the +maintainers. Follow the discussion on the #fabric-maintainers channel in Rocket +Chat. + +Making Feature/Enhancement Proposals +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, take time to review +`JIRA `__ +to be sure that there isn't already an open (or recently closed) proposal for the +same function. If there isn't, to make a proposal we recommend that you open a +JIRA Epic or Story, whichever seems to best fit the circumstance and +link or inline a "one pager" of the proposal that states what the feature would +do and, if possible, how it might be implemented. It would help also to make a +case for why the feature should be added, such as identifying specific use +case(s) for which the feature is needed and a case for what the benefit would be +should the feature be implemented. Once the JIRA issue is created, and the +"one pager" either attached, inlined in the description field, or a link to a +publicly accessible document is added to the description, send an introductory +email to the fabric@lists.hyperledger.org mailing list linking the +JIRA issue, and soliciting feedback. + +Discussion of the proposed feature should be conducted in the JIRA issue itself, +so that we have a consistent pattern within our community as to where to find +design discussion. + +Getting the support of three or more of the Hyperledger Fabric maintainers for +the new feature will greatly enhance the probability that the feature's related +CRs will be included in a subsequent release. + +Maintainers meeting +~~~~~~~~~~~~~~~~~~~ + +The maintainers hold a bi-weekly meeting every other Wednesday at 9 am ET +on `Zoom `__. Please see the +`community calendar `__ +for details. + +The purpose of the maintainers meeting is to plan for and review the progress of +releases, and to discuss the technical and operational direction of the project +and sub-projects. + +New feature/enhancement proposals as described above should be presented to a +maintainers meeting for consideration, feedback and acceptance. + +Release roadmap +~~~~~~~~~~~~~~~ + +The Fabric release roadmap of epics is maintained in +`JIRA `__. + +Communications +~~~~~~~~~~~~~~ + +We use `RocketChat `__ for communication +and Google Hangouts™ for screen sharing between developers. Our +development planning and prioritization is done in +`JIRA `__, and we take longer running +discussions/decisions to the `mailing +list `__. + +Contribution guide +------------------ Install prerequisites ---------------------- +~~~~~~~~~~~~~~~~~~~~~ Before we begin, if you haven't already done so, you may wish to check that you have all the :doc:`prerequisites ` installed on the platform(s) @@ -32,7 +121,7 @@ on which you'll be developing blockchain applications and/or operating Hyperledger Fabric. Getting a Linux Foundation account ----------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In order to participate in the development of the Hyperledger Fabric project, you will need a :doc:`Linux Foundation @@ -43,7 +132,7 @@ access to all the Hyperledger community development tools, including `Wiki `__ (for editing, only). Getting help ------------- +~~~~~~~~~~~~ If you are looking for something to work on, or need some expert assistance in debugging a problem or working out a fix to an issue, our @@ -57,7 +146,7 @@ ask. Questions are in fact a great way to help improve the project as they highlight where our documentation could be clearer. Reporting bugs --------------- +~~~~~~~~~~~~~~ If you are a user and you have found a bug, please submit an issue using `JIRA `__. @@ -79,7 +168,7 @@ be broadcast to ``#fabric-documentation``, a database bug to ``#fabric-ledger``, and so on... Submitting your fix -------------------- +~~~~~~~~~~~~~~~~~~~ If you just submitted a JIRA for a bug you've discovered, and would like to provide a fix, we would welcome that gladly! Please assign the JIRA issue to @@ -89,7 +178,7 @@ yourself, then you can submit a change request (CR). brief :doc:`tutorial ` for you. Fixing issues and working stories ---------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Review the `issues list `__ and find @@ -103,7 +192,7 @@ saying that you are still actively working the issue if you need a little more time. Reviewing submitted Change Requests (CRs) ------------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Another way to contribute and learn about Hyperledger Fabric is to help the maintainers with the review of the CRs that are open. Indeed @@ -121,40 +210,14 @@ will gain from it. Just browse through `the open CRs on Gerrit `__ to get started. -Making Feature/Enhancement Proposals ------------------------------------- - -Review -`JIRA `__. -to be sure that there isn't already an open (or recently closed) proposal for the -same function. If there isn't, to make a proposal we recommend that you open a -JIRA Epic, Story or Improvement, whichever seems to best fit the circumstance and -link or inline a "one pager" of the proposal that states what the feature would -do and, if possible, how it might be implemented. It would help also to make a -case for why the feature should be added, such as identifying specific use -case(s) for which the feature is needed and a case for what the benefit would be -should the feature be implemented. Once the JIRA issue is created, and the -"one pager" either attached, inlined in the description field, or a link to a -publicly accessible document is added to the description, send an introductory -email to the hyperledger-fabric@lists.hyperledger.org mailing list linking the -JIRA issue, and soliciting feedback. - -Discussion of the proposed feature should be conducted in the JIRA issue itself, -so that we have a consistent pattern within our community as to where to find -design discussion. - -Getting the support of three or more of the Hyperledger Fabric maintainers for the new -feature will greatly enhance the probability that the feature's related CRs -will be merged. - Setting up development environment ----------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Next, try :doc:`building the project ` in your local development environment to ensure that everything is set up correctly. What makes a good change request? ---------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - One change at a time. Not five, not three, not ten. One and only one. Why? Because it limits the blast area of the change. If we have a @@ -235,45 +298,6 @@ comments such that it gets to a point that it requires a rebase. It only further delays getting it merged and adds more work for you - to remediate the merge conflicts. -Communication --------------- - -We use `RocketChat `__ for communication -and Google Hangouts™ for screen sharing between developers. Our -development planning and prioritization is done in -`JIRA `__, and we take longer running -discussions/decisions to the `mailing -list `__. - -Maintainers ------------ - -The project's :doc:`maintainers ` are responsible for -reviewing and merging all patches submitted for review and they guide -the over-all technical direction of the project within the guidelines -established by the Hyperledger Technical Steering Committee (TSC). - -Becoming a maintainer -~~~~~~~~~~~~~~~~~~~~~ - -This project is managed under an open governance model as described in -our `charter `__. Projects or -sub-projects will be lead by a set of maintainers. New sub-projects can -designate an initial set of maintainers that will be approved by the -top-level project's existing maintainers when the project is first -approved. The project's maintainers will, from time-to-time, consider -adding or removing a maintainer. An existing maintainer can submit a -change set to the :doc:`MAINTAINERS.rst ` file. A nominated -Contributor may become a Maintainer by a majority approval of the proposal -by the existing Maintainers. Once approved, the change set is then merged -and the individual is added to (or alternatively, removed from) the maintainers -group. Maintainers may be removed by explicit resignation, for prolonged -inactivity (3 or more months), or for some infraction of the `code of conduct -`__ -or by consistently demonstrating poor judgement. A maintainer removed for -inactivity should be restored following a sustained resumption of contributions -and reviews (a month or more) demonstrating a renewed commitment to the project. - Legal stuff ----------- @@ -301,5 +325,23 @@ submitter accepts the DCO: You can include this automatically when you commit a change to your local git repository using ``git commit -s``. +Related Topics +-------------- + +.. toctree:: + :maxdepth: 1 + + MAINTAINERS + jira_navigation + dev-setup/devenv + dev-setup/build + Gerrit/lf-account + Gerrit/gerrit + Gerrit/changes + Gerrit/reviewing + Gerrit/best-practices + testing + Style-guides/go-style + .. Licensed under Creative Commons Attribution 4.0 International License https://creativecommons.org/licenses/by/4.0/