openstack/neutron
Code Issues Proposed changes

Move Neutron Policy pages into the tree

Browse Source 
The information from the NeutronPolicies wiki page [1] is useful. But
having it in a static wiki is less so. Moving this into the Neutron
documentation in-tree will allow for an easier maintenance of this
information.

[1] https://wiki.openstack.org/wiki/NeutronPolicies

Change-Id: I23cada04031e00f48c0f6dc26a992ed204195526
This commit is contained in:
Kyle Mestery 2015-03-05 17:34:05 +00:00 committed by Henry Gessau
parent a8873dc8d6
commit 2486842857
8 changed files with 292 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
doc/source/index.rst
View File

@ -39,6 +39,14 @@ The `Neutron Development wiki`_ is also a good resource for new contributors.
Enjoy!
Neutron Policies
================
.. toctree::
:maxdepth: 1
policies/index
Developer Docs
==============

10
doc/source/policies/blueprints.rst Normal file
View File

@ -0,0 +1,10 @@
Blueprints and Specs
====================
The Neutron team uses the `neutron-specs <http://git.openstack.org/cgit/openstack/neutron-specs>`_
repository for it's specification reviews. Detailed information can be found
`here <https://wiki.openstack.org/wiki/Blueprints#Neutron>`_. Please also find additional
information in the reviews.rst file.
Please note that at the start of each cycle, any BP/spec which did not make it in the release
will need to be resubmitted and approved for the next cycle.

37
doc/source/policies/bugs.rst Normal file
View File

@ -0,0 +1,37 @@
Neutron Bugs
============
Neutron maintains all of it's bugs in `Launchpad <https://bugs.launchpad.net/neutron>`_. All of
the current open Neutron bugs can be found in that link.
Neutron Bug Czar
----------------
Neutron maintains the notion of a "bug czar." The bug czar plays an important role in the Neutron
community. As a large project, Neutron is routinely fielding many bug reports. The bug czar is
responsible for acting as a "first contact" for these bug reports and performing initial
triaging. The bug czar is expected to communicate with the various Neutron teams when a bug has
been triaged. In addition, the bug czar should be reporting "High" and "Critical" priority bugs
to both the PTL and the core reviewer team during each weekly Neutron meeting.
The current Neutron bug czar is Eugene Nikanorov (IRC nick enikanorov).
Bug Triage Process
------------------
The process of bug triaging consists of the following steps:
1. Check if a bug was filed for a correct component (project). If not, either change the project
or mark it as "Invalid".
2. Add appropriate tags. Even if the bug is not valid or is a duplicate of another one, it still
may help bug submitters and corresponding sub-teams.
3. Check if a similar bug was filed before. If so, mark it as a duplicate of the previous bug.
4. Check if the bug description is consistent, e.g. it has enough information for developers to
reproduce it. If it's not consistent, ask submitter to provide more info and mark a bug as
"Incomplete".
5. Depending on ease of reproduction (or if the issue can be spotted in the code), mark it as
"Confirmed".
6. Assign the importance. Bugs that obviously break core and widely used functionality should get
assigned as "High" or "Critical" importance. The same applies to bugs that were filed for gate
failures.
7. (Optional). Add comments explaining the issue and possible strategy of fixing/working around
the bug.

42
doc/source/policies/code-reviews.rst Normal file
View File

@ -0,0 +1,42 @@
Neutron Code Reviews
====================
Code reviews are a critical component of all OpenStack projects. Neutron accepts patches from many
diverse people with diverse backgrounds, employers, and experience levels. Code reviews provide a
way to enforce a level of consistency across the project, and also allow for the careful on boarding
of contributions from new contributors.
Neutron Code Review Practices
-----------------------------
Neutron follows the `code review guidelines <https://wiki.openstack.org/wiki/ReviewChecklist>`_ as
set forth for all OpenStack projects. It is expected that all reviewers are following the guidelines
set forth on that page.
Neutron Spec Review Practices
-----------------------------
In addition to code reviews, Neutron also maintains a BP specification git repository. Detailed
instructions for the use of this repository are provided `here <https://wiki.openstack.org/wiki/Blueprints>`_.
It is expected that Neutron core team members are actively reviewing specifications which are pushed out
for review to the specification repository. In addition, there is a neutron-drivers team, composed of a
handful of Neutron core reviewers, who can approve and merge Neutron specs.
Some guidelines around this process are provided below:
* Once a specification has been pushed, it is expected that it will not be approved for at least 3 days
after a first Neutron core reviewer has reviewed it. This allows for additional cores to review the
specification.
* For blueprints which the core team deems of High or Critical importance, core reviewers may be assigned
based on their subject matter expertise.
* Specification priority will be set by the PTL with review by the core team once the specification is
approved.
Tracking Review Statistics
--------------------------
Stackalytics provides some nice interfaces to track review statistics. The links are provided below. These
statistics are used to track not only Neutron core reviewer statistics, but also to track review statistics
for potential future core members.
* `30 day review stats <http://stackalytics.com/report/contribution/neutron-group/30>`_
* `60 day review stats <http://stackalytics.com/report/contribution/neutron-group/60>`_
* `90 day review stats <http://stackalytics.com/report/contribution/neutron-group/90>`_
* `180 day review stats <http://stackalytics.com/report/contribution/neutron-group/180>`_

28
doc/source/policies/contributor-onboarding.rst Normal file
View File

@ -0,0 +1,28 @@
Contributor Onboarding
======================
For new contributors, the following are useful onboarding information.
Contributing to Neutron
-----------------------
Work within Neutron is discussed on the openstack-dev mailing list, as well as in the
#openstack-neutron IRC channel. While these are great channels for engaging Neutron,
the bulk of discussion of patches and code happens in gerrit itself.
With regards to gerrit, code reviews are a great way to learn about the project. There
is also a list of `low or wishlist <https://bugs.launchpad.net/neutron/+bugs?field.searchtext=&orderby=-importance&field.status%3Alist=NEW&field.status%3Alist=CONFIRMED&field.status%3Alist=TRIAGED&field.status%3Alist=INPROGRESS&field.status%3Alist=FIXCOMMITTED&field.status%3Alist=INCOMPLETE_WITH_RESPONSE&field.status%3Alist=INCOMPLETE_WITHOUT_RESPONSE&field.importance%3Alist=LOW&field.importance%3Alist=WISHLIST&assignee_option=any&field.assignee=&field.bug_reporter=&field.bug_commenter=&field.subscriber=&field.structural_subscriber=&field.tag=&field.tags_combinator=ANY&field.has_cve.used=&field.omit_dupes.used=&field.omit_dupes=on&field.affects_me.used=&field.has_patch.used=&field.has_branches.used=&field.has_branches=on&field.has_no_branches.used=&field.has_no_branches=on&field.has_blueprints.used=&field.has_blueprints=on&field.has_no_blueprints.used=&field.has_no_blueprints=on&search=Search>`_ priority bugs which are ideal for a new contributor to take
on. If you haven't done so you should setup a Neutron development environment so you
can actually run the code. Devstack is the usual convenient environment to setup such
an environment. See `devstack.org <http://devstack.org/>`_ or `NeutronDevstack <https://wiki.openstack.org/wiki/NeutronDevstack#Basic_Setup>`_
for more information on using Neutron with devstack.
Helping with documentation can also be a useful first step for a newcomer. `Here <https://bugs.launchpad.net/openstack-manuals/+bugs?field.tag=neutron>`_
is a list of documentation bugs that are tagged with 'neutron'; bug reports are created
here for neutron reviews with a 'DocImpact' in the commit message.
IRC Information and Etiquette
-----------------------------
The main IRC channel for Neutron is #openstack-neutron. We also utilize #openstack-lbaas
for LBaaS specific discussions. The weekly meeting is documented in the `list of meetings <https://wiki.openstack.org/wiki/Meetings#OpenStack_Networking_.28Neutron.29>`_ wiki page.

57
doc/source/policies/core-reviewers.rst Normal file
View File

@ -0,0 +1,57 @@
Core Neutron Reviewers
======================
The `Neutron Core Reviewer Team <https://review.openstack.org/#/admin/groups/38,members>`_ is responsible
for merging changes into the following repositories:
* `openstack/neutron <https://git.openstack.org/cgit/openstack/neutron/>`_
* `openstack/neutron-fwaas <https://git.openstack.org/cgit/openstack/neutron-fwaas/>`_
* `openstack/neutron-lbaas <https://git.openstack.org/cgit/openstack/neutron-lbaas/>`_
* `openstack/neutron-vpnaas <https://git.openstack.org/cgit/openstack/neutron-vpnaas/>`_
* `openstack/python-neutronclient <https://git.openstack.org/cgit/openstack/python-neutronclient/>`_
* `openstack/neutron-specs <https://git.openstack.org/cgit/openstack/neutron-specs/>`_
While everyone is encouraged to review changes for these repositories, members of the neutron-core
gerrit group have the ability to +2/-2 and +A changes these repositories. This is responsibility
that is not to be taken lightly.
Adding or Removing Core Reviewers
---------------------------------
A new Neutron core reviewer may be proposed at anytime on the openstack-dev mailing list. Typically,
the Neutron PTL will propose a new member after discussions with the existing core reviewers. Once
a proposal has been made, five existing Neutron core reviewers must respond to the email with a +1.
Another Neutron core reviewer can vote -1 to veto the proposed new core reviewer.
The PTL may remove a Neutron core reviewer at any time. Typically when a member has decreased their
involvement with the project through a drop in reviews and participation in general project development,
the PTL will propose their removal and remove them. Please note there is no voting or vetoing of
core reviewer removal. Members who have previously been a core reviewer may be fast-tracked back into
a core reviewer role if their involvement picks back up and the existing core reviewers support their
re-instatement.
Core Reviewer Membership Expectations
-------------------------------------
Neutron core reviewers have the following expectations:
* Reasonable attendance at the weekly Neutron IRC meetings.
* Participation in Neutron discussions on the mailing list, as well as in-channel in #openstack-neutron.
* Participation in Neutron related design summit sessions at the OpenStack Summits.
In addition to the above, code reviews are the most important requirement of Neutron core reviewers.
Neutron follows the documented OpenStack `code review guidelines <https://wiki.openstack.org/wiki/ReviewChecklist>`_.
We encourage all people to review Neutron patches, but core reviewers are required to maintain a level of
review numbers relatively close to other core reviewers. There are no hard statistics around code review
numbers, but in general we use 30, 60, 90 and 180 day stats when examining review stats.
* `30 day review stats <http://stackalytics.com/report/contribution/neutron-group/30>`_
* `60 day review stats <http://stackalytics.com/report/contribution/neutron-group/60>`_
* `90 day review stats <http://stackalytics.com/report/contribution/neutron-group/90>`_
* `180 day review stats <http://stackalytics.com/report/contribution/neutron-group/180>`_
There are soft-touch items around being a Neutron core reviewer as well. Gaining trust with the existing Neutron
core reviewers is important. Being able to work together with the existing Neutron core review team is critical
as well. Being a Neutron core reviewer means spending a significant amount of time with the existing Neutron
core reviewer team on IRC, the mailing list, at Summits, and in reviews. Ensuring you participate and engage
here is critical to becoming and remaining a core.

69
doc/source/policies/gate-failure-triage.rst Normal file
View File

@ -0,0 +1,69 @@
Neutron Gate Failure Triage
===========================
This page provides guidelines for spotting and assessing neutron gate failures. Some hints for triaging
failures are also provided.
Spotting Gate Failures
----------------------
This can be achieved using several tools:
* `Joe Gordon's github.io pages <http://jogo.github.io/gate/>`_
* `logstash <http://logstash.openstack.org/>`_
Even though Joe's script is not an "official" OpenStack page it provides a quick snapshot of the current
status for the most important jobs This page is built using data available at graphite.openstack.org.
If you want to check how that is done go `here <https://github.com/jogo/jogo.github.io/tree/master/gate>`_
(caveat: the color of the neutron job is very similar to that of the full job with nova-network).
For checking gate failures with logstash the following query will return failures for a specific job:
> build_status:FAILURE AND message:Finished AND build_name:"check-tempest-dsvm-neutron" AND build_queue:"gate"
And divided by the total number of jobs executed:
> message:Finished AND build_name:"check-tempest-dsvm-neutron" AND build_queue:"gate"
It will return the failure rate in the selected period for a given job. It is important to remark that
failures in the check queue might be misleading as the problem causing the failure is most of the time in
the patch being checked. Therefore it is always advisable to work on failures occurred in the gate queue.
However, these failures are a precious resource for assessing frequency and determining root cause of
failures which manifest in the gate queue.
The step above will provide a quick outlook of where things stand. When the failure rate raises above 10% for
a job in 24 hours, it's time to be on alert. 25% is amber alert. 33% is red alert. Anything above 50% means
that probably somebody from the infra team has already a contract out on you. Whether you are relaxed, in
alert mode, or freaking out because you see a red dot on your chest, it is always a good idea to check on
daily bases the elastic-recheck pages.
Under the `gate pipeline <http://status.openstack.org/elastic-recheck/gate.html>`_ tab, you can see gate
failure rates for already known bugs. The bugs in this page are ordered by decreasing failure rates (for the
past 24 hours). If one of the bugs affecting Neutron is among those on top of that list, you should check
that the corresponding bug is already assigned and somebody is working on it. If not, and there is not a good
reason for that, it should be ensured somebody gets a crack at it as soon as possible. The other part of the
story is to check for `uncategorized <http://status.openstack.org/elastic-recheck/data/uncategorized.html>`_
failures. This is where failures for new (unknown) gate breaking bugs end up; on the other hand also infra
error causing job failures end up here. It should be duty of the diligent Neutron developer to ensure the
classification rate for neutron jobs is as close as possible to 100%. To this aim, the diligent Neutron
developer should adopt the following procedure:
1. Open logs for failed jobs and look for logs/testr_results.html.gz.
2. If that file is missing, check console.html and see where the job failed.
1. If there is a failure in devstack-gate-cleanup-host.txt it's likely to be an infra issue.
2. If the failure is in devstacklog.txt it could a devstack, neutron, or infra issue.
3. However, most of the time the failure is in one of the tempest tests. Take note of the error message and go to
logstash.
4. On logstash, search for occurrences of this error message, and try to identify the root cause for the failure
(see below).
5. File a bug for this failure, and push a elastic-recheck query for it (see below).
6. If you are confident with the area of this bug, and you have time, assign it to yourself; otherwise look for an
assignee or talk to the Neutron's bug czar to find an assignee.
Root Causing a Gate Failure
---------------------------
Time-based identification, i.e. find the naughty patch by log scavenging.
Filing An Elastic Recheck Query
-------------------------------
The `elastic recheck <http://status.openstack.org/elastic-recheck/>`_ page has all the current open ER queries.
To file one, please see the `ER Wiki <https://wiki.openstack.org/wiki/ElasticRecheck>`_.

41
doc/source/policies/index.rst Normal file
View File

@ -0,0 +1,41 @@
..
Copyright 2014 Hewlett-Packard Development Company, L.P.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Neutron Policies
================
In the Policies Guide, you will find documented policies for developing with
Neutron. This includes the processes we use for blueprints and specs, bugs,
contributor onboarding, core reviewer memberships, and other procedural
items.
Policies
--------
.. toctree::
:maxdepth: 3
blueprints
bugs
contributor-onboarding
core-reviewers
gate-failure-triage
code-reviews
Indices and tables
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`