Skip to content

Commit

Permalink
FAB-12199 update Contributing Guide
Browse files Browse the repository at this point in the history 
added section on project governance to make clearer how
we operate. Feedback welcomed.

Change-Id: I044308f4b040d99577f80729d9af377531e206ee
Signed-off-by: Christopher Ferris <chrisfer@us.ibm.com>
  • Loading branch information
@christo4ferris
christo4ferris committed Sep 27, 2018
1 parent 3536c50 commit cfc3d83
Showing 1 changed file with 129 additions and 87 deletions.
216 changes: 129 additions & 87 deletions docs/source/CONTRIBUTING.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,31 +8,120 @@ First things first, please review the Hyperledger `Code of
Conduct <https://wiki.hyperledger.org/community/hyperledger-project-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 <https://www.hyperledger.org/about/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 <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 <MAINTAINERS>` 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
<https://wiki.hyperledger.org/community/hyperledger-project-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 <https://github.com/hyperledger/fabric#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 <https://jira.hyperledger.org/issues/?filter=12524>`__
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 <https://zoom.us/my/hyperledger.community>`__. Please see the
`community calendar <https://wiki.hyperledger.org/community/calendar-public-meetings>`__
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 <https://jira.hyperledger.org/secure/Dashboard.jspa?selectPageId=10104>`__.

Communications
~~~~~~~~~~~~~~

We use `RocketChat <https://chat.hyperledger.org/>`__ for communication
and Google Hangouts™ for screen sharing between developers. Our
development planning and prioritization is done in
`JIRA <https://jira.hyperledger.org>`__, and we take longer running
discussions/decisions to the `mailing
list <https://lists.hyperledger.org/mailman/listinfo/hyperledger-fabric>`__.

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 <prereqs>` installed on the platform(s)
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
Expand All @@ -43,7 +132,7 @@ access to all the Hyperledger community development tools, including
`Wiki <https://wiki.hyperledger.org/start>`__ (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
Expand All @@ -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 <https://jira.hyperledger.org/secure/Dashboard.jspa?selectPageId=10104>`__.
Expand All @@ -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
Expand All @@ -89,7 +178,7 @@ yourself, then you can submit a change request (CR).
brief :doc:`tutorial <submit_cr>` for you.

Fixing issues and working stories
---------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Review the `issues
list <https://jira.hyperledger.org/issues/?filter=10580>`__ and find
Expand All @@ -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
Expand All @@ -121,40 +210,14 @@ will gain from it.
Just browse through `the open CRs on Gerrit
<https://gerrit.hyperledger.org/r/#/q/status:open>`__ to get started.

Making Feature/Enhancement Proposals
------------------------------------

Review
`JIRA <https://jira.hyperledger.org/secure/Dashboard.jspa?selectPageId=10104>`__.
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 <dev-setup/build>` 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
Expand Down Expand Up @@ -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 <https://chat.hyperledger.org/>`__ for communication
and Google Hangouts™ for screen sharing between developers. Our
development planning and prioritization is done in
`JIRA <https://jira.hyperledger.org>`__, and we take longer running
discussions/decisions to the `mailing
list <https://lists.hyperledger.org/mailman/listinfo/hyperledger-fabric>`__.

Maintainers
-----------

The project's :doc:`maintainers <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 <https://www.hyperledger.org/about/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 <MAINTAINERS>` 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
<https://wiki.hyperledger.org/community/hyperledger-project-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
-----------

Expand Down Expand Up @@ -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/

0 comments on commit cfc3d83

Please sign in to comment.