PEP 8002: add OpenStack governance summary (#766)

pep-8002.rst

@@ -1,7 +1,7 @@
 PEP: 8002
 Title: Open Source Governance Survey
 Author: Barry Warsaw <barry@python.org>, Łukasz Langa <lukasz@python.org>,
-   Antoine Pitrou <solipsis@pitrou.net>
+   Antoine Pitrou <solipsis@pitrou.net>, Doug Hellmann <doug@doughellmann.com>
 Status: Active
 Type: Informational
 Content-Type: text/x-rst
@@ -166,12 +166,220 @@ discussion and enable reacting to a change *about to* being made, instead of hav
 revert a rushed decision that was already made.
 
 
+OpenStack
+=========
+
+The OpenStack Foundation Bylaws lay out the basic structure for
+project governance, with `Article IV
+<https://www.openstack.org/legal/bylaws-of-the-openstack-foundation/>`__
+delegating day-to-day management of the open source project to the
+OpenStack Technical Committee (TC), and `The TC member policy
+<https://www.openstack.org/legal/technical-committee-member-policy/>`__
+defining broadly how the Technical Committee shall be elected. The TC
+publishes a set of more detailed `governance documents
+<https://governance.openstack.org/tc/>`__, including `the TC charter
+<https://governance.openstack.org/tc/reference/charter.html>`__, which
+describes the team structure, precise rules for establishing
+eligibility to run for office, and criteria for establishing the
+various electorates.
+
+Key people and their functions
+------------------------------
+
+The OpenStack community is made up of many distinct `project teams
+<https://governance.openstack.org/tc/reference/projects/index.html>`__,
+responsible for producing different components of the software (block
+storage management, compute management, etc.) or managing different
+parts of the processes the community follows (such as tracking the
+release schedule).  Each team is led by a *Project Team Lead* (PTL),
+elected by the *Active Project Contributors* for that project.
+
+Active Project Contributors (APCs) are recent contributors to a given
+project team.  APC status formally requires two things: becoming an
+individual member of the OpenStack Foundation (membership is free) and
+having a change merged within the last year (two development cycles)
+in a repository managed by a project team.
+
+The elected PTL serves a term equal to one development cycle (roughly
+6 months). There is no restriction on the number of consecutive terms
+a person may serve as PTL, and it is common for someone to serve for
+several terms in a row. It is also not unusual for a team to have only
+one candidate volunteer to serve as PTL for a given cycle, in which
+case there is no need for an election.
+
+The PTL represents the team in all cases except where they have
+explicitly delegated some responsibility. For example, many teams
+designate a separate *release liaison* to manage the release process
+for a development cycle.  The PTL also serves as a final decision
+maker in cases where consensus cannot be reached between the team
+members.
+
+While the APCs all vote for the PTL of a team, in many other cases
+only the *core reviewer* team will be consulted on policy decisions
+for the team. Anyone may review any patch for any OpenStack
+project. After someone demonstrates that they have a good grasp of the
+technical issues of a project, that they provide useful feedback on
+reviews, and that they understand the direction the project is going,
+they may be invited to become a member of the core review team. Unlike
+in many other communities, this status does not grant them the right
+to submit code without having it reviewed. Rather, it asks them to
+commit to reviewing code written by other contributors, and to
+participate in team decision-making discussions. Asking someone to
+become a member of the core review team is a strong indication of
+trust.
+
+The Technical Committee (TC) is responsible for managing the
+development of OpenStack as a whole.  The 13 members of the Technical
+Committee are directly elected by APCs from all project teams. Each
+member serves a term of two development cycles (roughly 1 year), with
+the elections split so that only about half of the members' terms
+expire at any time, to ensure continuity. The TC establishes overall
+policies, such as the criteria for adding new project teams, the
+deprecation policy for Python 2, testing requirements, etc.
+
+Regular decision process
+------------------------
+
+All elections for PTL or TC members use https://civs.cs.cornell.edu to
+run a *Condorcet* election. This system was selected because it
+emphasizes consensus candidates over strict popularity.
+
+The OpenStack contributor community relies on 3 primary tools for
+discussion: the `openstack-dev mailing list
+<http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev>`__,
+a gerrit code review instance at https://review.openstack.org, and a
+set of `OpenStack-specific IRC channels
+<http://eavesdrop.openstack.org>`__ on Freenode. There are a few teams
+whose contributors are based primarily in China, and they have trouble
+accessing IRC. Those teams tend to use alternative platforms such as
+WeChat, instead.
+
+The tool used for discussing any given decision will vary based on its
+weight and impact. Everyone is encouraged to use either the mailing
+list or gerrit to support asynchronous discussion across a wider range
+of timezones and and firewalls, especially for publicizing final
+decisions for the rest of the community.
+
+Policy decisions limited to a single team are usually made by the core
+review team for a project, and the policies and decision processes may
+vary between teams.  Some groups write down their team policies in
+their documentation repository, and use the code review tool (gerrit)
+to vote on them. Some teams discuss policies on IRC, either ad hoc or
+during a regularly scheduled meeting, and make decisions there.  Some
+teams use the mailing list for those discussions. The PTL for the team
+is responsible for ensuring the discussion is managed and the outcome
+is communicated (either by doing so directly or ensuring that the task
+is delegated to someone else).
+
+All team policy decisions need to be compatible with the overall
+policies set by the Technical Committee. Because the TC tends to make
+broader governance decisions that apply to the entire contributor
+community, the process for discussing and voting on those decisions is
+described more formally, including specifying the number of votes
+needed to pass and the minimum length of time required for
+discussion. For example, most motions require 1/3 of the members (5)
+to pass and must stay open at least 3 days after receiving sufficient
+votes to pass, ensuring that there is time for dissent to be
+registered. See the `Technical Committee Charter
+<https://governance.openstack.org/tc/reference/charter.html#motions>`__
+and `house rules
+<https://governance.openstack.org/tc/reference/house-rules.html>`__
+for more details.
+
+Significant design decisions are usually discussed by reviewing a
+`specification document <http://specs.openstack.org>`__, somewhat
+similar to a PEP, that covers the requirements, alternatives, and
+implementation details. Feedback is solicited from all contributors,
+and then specifications are eventually approved or rejected by members
+of the core review team for a project. Some teams require only 2
+reviewers to approve a design, while other teams require a stronger
+indication of consensus before a design is approved. Each team sets a
+`deadline for approving specifications within each development cycle
+<https://releases.openstack.org/rocky/schedule.html>`__, to encourage
+contributors to work out designs for significant new features early
+and avoid risk from changes late in the cycle.
+
+Smaller technical decisions are typically made by reviewing the
+patch(es) needed to implement the change. Anyone may review any patch
+and provide technical feedback, but ultimately two core reviewers for
+a team are needed to approve most changes (exceptions are often made
+for trivial changes such as typos or for fixes that unblock the CI
+gating system).
+
+Controversial decision process
+------------------------------
+
+Controversial, or merely complicated, decisions frequently expand
+outside of specification reviews to mailing list discussions. They
+often also result in discussions at one of the regularly scheduled
+in-person community gatherings. Because many members of the community
+cannot attend these events, the discussions are summarized and final
+decisions are made using on-line tools as much as possible.
+
+The PTL is responsible for deciding when consensus has been reached
+for decisions that affect a single team, and to make a final call in
+rare cases where consensus has not been reached and a decision
+absolutely needs to be made.  The TC acts as a similar decision-making
+group of last resort for cases where issues *between* teams cannot be
+resolved in another way. Such escalation of decision-making ends up
+being rarely necessary, because the contributors directly involved
+generally prefer to come to a consensual agreement rather than
+escalate the decision to others.
+
+Planning a new release
+----------------------
+
+OpenStack has a major release about every 6 months. These are
+coordinated date-based releases, which include the work finished up to
+that point in time in all of the member projects. Some project teams
+release more often than every 6 months (this is especially true for
+teams building libraries consumed by other teams). Those smaller
+releases tend to be produced when there is content (new features or
+bug fixes) to justify them.
+
+The schedule for each development cycle, with deadlines and a final
+release date, is proposed by the release management team, in
+coordination with the Foundation staff (releases are generally aligned
+with the calendar of in-person events), and then the community has an
+opportunity to provide feedback before the final dates are set.
+
+Decisions about priorities for each development cycle are made at the
+team level and the TC level. Core review teams prioritize internal
+work, such as fixing bugs and implementing new features. The TC
+selects `community goals
+<https://governance.openstack.org/tc/goals/index.html>`__, which
+usually require some amount of work from all teams. Agreeing to these
+priorities at the start of each cycle helps the teams coordinate their
+work, which is especially important because the implementation will
+require reviews from multiple team members.
+
+Changes in the process over time
+--------------------------------
+
+Over the last 8 years the number of OpenStack project teams has grown
+from 2 to 63. The makeup of the Technical Committee has changed to
+accommodate that growth. Originally the TC was made up of PTLs, but as
+the membership grew it became impractical for the group to function
+effectively.
+
+The community also used to be organized around "program areas" rather
+than project teams. A program area covered a feature set, such as
+gathering telemetry or managing block storage. This organization
+failed when multiple teams of people wanted to work on the same
+feature set using different solutions. Organizing teams around the
+code they deliver allows different teams to have different
+interpretations of the same requirements. For example, there are now
+several teams working on different deployment tools.
+
 Acknowledgements
 ================
 
 Thank you to Alex Crichton from the Rust team for an extensive explanation of how the
 core team governs the project.
 
+Jeremy Stanley, Chris Dent, Julia Kreger, Sean McGinnis, Emmet Hikory,
+and Thierry Carrez contributed to the OpenStack section.
+
 
 Annex 1: Template questions
 ===========================