Team Structure policy document
Added a new Fuel Policy Documents section with a new policy document on Fuel Team Structure. Following additional changes were made to make this patch build cleanly: * basepython = python to prevent tox on Debian from using python3 * autogenerated doc/source/index.rst added to .gitignore * policy directory and symlink created and reflected in header template Change-Id: I66149c3edcb99b8b6f130518fe6ca8239864036a
This commit is contained in:
Dmitry Borodaenko
parent
12ba603294
commit
61c4a87ea3
|
|
@ -16,6 +16,7 @@ draft/
|
|||
/.testrepository
|
||||
/.tox
|
||||
/doc/build
|
||||
/doc/source/index.rst
|
||||
|
||||
ChangeLog
|
||||
AUTHORS
|
||||
AUTHORS
|
||||
|
|
|
|||
|
|
@ -1,11 +1,20 @@
|
|||
.. fuel-specs documentation master file
|
||||
|
||||
=====================
|
||||
Fuel Policy Documents
|
||||
=====================
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
policy/*
|
||||
|
||||
|
||||
===========================
|
||||
Fuel Project Specifications
|
||||
===========================
|
||||
|
||||
Contents:
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
|
|
|||
|
|
@ -0,0 +1 @@
|
|||
../../policy
|
||||
|
|
@ -0,0 +1,209 @@
|
|||
================
|
||||
Team Structure
|
||||
================
|
||||
|
||||
This document describes the structure of the Fuel team and how it is used to
|
||||
organize code review, design discussions, and overall technical decision making
|
||||
process in the Fuel project.
|
||||
|
||||
Problem Description
|
||||
===================
|
||||
|
||||
Code review is the primary tool for day to day interactions between Fuel
|
||||
contributors. Problems with code review process can be grouped into two
|
||||
buckets.
|
||||
|
||||
It is hard to get code reviewed and merged:
|
||||
|
||||
1. It is hard to find subject matter experts and core reviewers for the
|
||||
specific part of codebase, especially if you are new to the project.
|
||||
|
||||
2. Contributor sometimes receives contradicting opinions from different
|
||||
reviewers, including cores.
|
||||
|
||||
3. Without an assigned core reviewer, it is hard to guide a feature through
|
||||
architectural negotiations and code review process to landing the code into
|
||||
master.
|
||||
|
||||
4. Some commits are waiting for a long time for a reviewer.
|
||||
|
||||
Quality of code review itself could be better:
|
||||
|
||||
5. Reviews are not thorough enough. Instead of examining the whole patch set
|
||||
and identifying all problems in one shot, a reviewer can leave a -1 vote
|
||||
after identifying only one minor problem. This increases number of patch
|
||||
sets per commit, and demotivates contributors.
|
||||
|
||||
6. Some of the core reviewers decreased their involvement, and so number of
|
||||
reviews has dropped dramatically. However, they still occasionally merge
|
||||
code.
|
||||
|
||||
7. As a legacy of the past, we still have old core reviewers being able to
|
||||
merge code in all Fuel repos. All new cores have core rights only for single
|
||||
repo, which is their primary area of expertise.
|
||||
|
||||
Having well defined areas of ownership in Fuel components addreses most of
|
||||
these problems: from making it easier to identify the right reviewers for your
|
||||
code, to prioritizing code review work so that core reviewers can spend more
|
||||
attention on smaller number of commits.
|
||||
|
||||
Proposed Policy
|
||||
===============
|
||||
|
||||
Definitions
|
||||
-----------
|
||||
|
||||
Contributor:
|
||||
Submitter of a code review, who doesn't necessarily work on Fuel regularly,
|
||||
may not be familiar with the team structure or with Fuel codebase.
|
||||
|
||||
Maintainer:
|
||||
Subject matter expert in certain Fuel area of code, which they regularly
|
||||
contribute to and review code of other contributors into this area. For
|
||||
example: network checker or Nailgun agent would have their own lists of
|
||||
maintainers.
|
||||
|
||||
List of maintainers for different parts of a Fuel git repository is
|
||||
provided in a MAINTAINERS file at the top level of that repository. A
|
||||
repository that contains multiple components may have multiple MAINTAINERS
|
||||
files in the component subdirectories.
|
||||
|
||||
Core Reviewer:
|
||||
Maintainer who has maintained high level of contribution and high quality
|
||||
of code reviews and was promoted to core reviewers team by consensus of
|
||||
other core reviewers of the same Fuel component.
|
||||
|
||||
Component Lead:
|
||||
Defines architecture of a particular module or component in Fuel, resolves
|
||||
technical disputes in their area of responsibility. All design specs that
|
||||
impact a component must be approved by the corresponding component lead.
|
||||
|
||||
Fuel PTL:
|
||||
Project Team Lead in its OpenStack standard definition. Delegates most of
|
||||
the review and design work to component leads, resolves technical disputes
|
||||
across components and for components that don't have dedicated component
|
||||
leads.
|
||||
|
||||
Code Review Workflow
|
||||
--------------------
|
||||
|
||||
Typical commit goes through the following code review stages:
|
||||
|
||||
0. Contributor makes sure their commit receives no negative votes from CI. When
|
||||
possible, contributor also invites peers to review their commit, preferably
|
||||
from different locations to help spread out the knowledge of the new code.
|
||||
|
||||
1. Contributor finds the maintainers for the areas of the code modified by
|
||||
their commit in the MAINTAINERS file, and invites them to the review.
|
||||
|
||||
2. Once maintainer is ready to add +1 code review vote to the commit, they
|
||||
invite core reviewers of the modified component to the review.
|
||||
|
||||
3. A commit that has a +2 vote from a core reviewer can be merged by another
|
||||
core reviewer (may be the same core reviewer if the repository has only 2 or
|
||||
less core reviewers), or by the component lead of the modified component.
|
||||
|
||||
Governance Process
|
||||
------------------
|
||||
|
||||
Fuel PTL is elected twice a year following the same cycle and rules as other
|
||||
OpenStack projects: all committers to all Fuel projects (fuel-* and
|
||||
python-fuelclient) over the last year can vote and can self-nominate.
|
||||
|
||||
Fuel component leads are elected twice a year immediately after PTL elections,
|
||||
following the same process. All committers to the component code repository as
|
||||
defined below over the last year can vote and can self-nominate. Same person
|
||||
can't be PTL and component lead in the same cycle.
|
||||
|
||||
Following Fuel components have elected leads:
|
||||
|
||||
* fuel-library (code: fuel-library)
|
||||
|
||||
* fuel-python (code: fuel-web except fuel-ui that currently lives under
|
||||
fuel-web/nailgun/static)
|
||||
|
||||
In other repositories, there is no component leads, and technical decisions are
|
||||
made by consensus of core reviewers, and disputes are resolved by Fuel PTL.
|
||||
|
||||
.. note::
|
||||
|
||||
All fuel-ui developers are also committers to fuel-web and are still
|
||||
eligible to vote for the fuel-python component lead. However, fuel-ui itself
|
||||
is not governed by the fuel-python component lead and follows the governance
|
||||
process for repositories without component leads.
|
||||
|
||||
Core reviewers are approved by consensus of existing core reviewers, following
|
||||
the same process as with other OpenStack projects. Core reviewers can
|
||||
voluntarily step down, or be removed by consensus of existing core reviewers.
|
||||
Separate core reviewers list is maintained for each Fuel git repository.
|
||||
|
||||
Maintainers are defined by the contents of the MAINTAINERS files in Fuel git
|
||||
repositories, following the standard code review process. Any contributor can
|
||||
propose an update of a MAINTAINERS file; a core reviewer can approve an update
|
||||
that has a +2 from another core reviewer; if the update adds new maintainers,
|
||||
it must also have +1 votes from all added maintainers.
|
||||
|
||||
Alternatives
|
||||
============
|
||||
|
||||
Flat project structure
|
||||
----------------------
|
||||
|
||||
Many other OpenStack projects keep a flat team structure: one elected PTL, and
|
||||
a single list of core reviewers for the whole project. The advantage is a more
|
||||
simple and straightforward governance process. The disadvantages are described
|
||||
in the problem description.
|
||||
|
||||
Split Fuel into sub-projects
|
||||
----------------------------
|
||||
|
||||
An alternative way to address the problem of insufficiently granular ownership
|
||||
is to split Fuel into several sub-projects with independent governance. The
|
||||
advantage is not having to introduce the role of a component lead that doesn't
|
||||
exist in other OpenStack projects. The disadvantage is even more governance
|
||||
overhead, and having to involve the Technical Committee in cross-sub-project
|
||||
dispute resolution.
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
||||
Author(s)
|
||||
---------
|
||||
|
||||
Primary author: mihgen (Mike Scherbakov)
|
||||
|
||||
Other contributors: angdraug (Dmitry Borodaenko)
|
||||
|
||||
Milestones
|
||||
----------
|
||||
|
||||
The current policy was put in place for Mitaka.
|
||||
|
||||
Work Items
|
||||
----------
|
||||
|
||||
N/A
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
* OpenStack Governance process:
|
||||
https://wiki.openstack.org/wiki/Governance
|
||||
|
||||
* Code review process in Fuel and related issues (by Mike Scherbakov):
|
||||
http://lists.openstack.org/pipermail/openstack-dev/2015-August/072406.html
|
||||
|
||||
* Fuel Review Inbox (by Dmitry Borodaenko):
|
||||
http://git.openstack.org/cgit/stackforge/gerrit-dash-creator/tree/dashboards/fuel.dash
|
||||
|
||||
* Fuel contribution statistics (Stackalytics):
|
||||
http://stackalytics.com/report/contribution/fuel-group/90
|
||||
|
||||
* Open Reviews for Fuel (by Russel Bryant):
|
||||
http://russellbryant.net/openstack-stats/fuel-openreviews.html
|
||||
|
||||
.. note::
|
||||
|
||||
This work is licensed under a Creative Commons Attribution 3.0
|
||||
Unported License.
|
||||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||
Loading…
Reference in New Issue