diff --git a/doc/source/index.rst b/doc/source/index.rst index 51c63d277ec..0f2553b371c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 ============== diff --git a/doc/source/policies/blueprints.rst b/doc/source/policies/blueprints.rst new file mode 100644 index 00000000000..3de00780392 --- /dev/null +++ b/doc/source/policies/blueprints.rst @@ -0,0 +1,10 @@ +Blueprints and Specs +==================== + +The Neutron team uses the `neutron-specs `_ +repository for it's specification reviews. Detailed information can be found +`here `_. 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. diff --git a/doc/source/policies/bugs.rst b/doc/source/policies/bugs.rst new file mode 100644 index 00000000000..6e2e1021035 --- /dev/null +++ b/doc/source/policies/bugs.rst @@ -0,0 +1,37 @@ +Neutron Bugs +============ + +Neutron maintains all of it's bugs in `Launchpad `_. 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. diff --git a/doc/source/policies/code-reviews.rst b/doc/source/policies/code-reviews.rst new file mode 100644 index 00000000000..bdc102c9e3a --- /dev/null +++ b/doc/source/policies/code-reviews.rst @@ -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 `_ 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 `_. +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 `_ +* `60 day review stats `_ +* `90 day review stats `_ +* `180 day review stats `_ diff --git a/doc/source/policies/contributor-onboarding.rst b/doc/source/policies/contributor-onboarding.rst new file mode 100644 index 00000000000..6c792bb786a --- /dev/null +++ b/doc/source/policies/contributor-onboarding.rst @@ -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 `_ 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 `_ or `NeutronDevstack `_ +for more information on using Neutron with devstack. + +Helping with documentation can also be a useful first step for a newcomer. `Here `_ +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 `_ wiki page. diff --git a/doc/source/policies/core-reviewers.rst b/doc/source/policies/core-reviewers.rst new file mode 100644 index 00000000000..2d0c3b6fd5d --- /dev/null +++ b/doc/source/policies/core-reviewers.rst @@ -0,0 +1,57 @@ +Core Neutron Reviewers +====================== + +The `Neutron Core Reviewer Team `_ is responsible +for merging changes into the following repositories: + +* `openstack/neutron `_ +* `openstack/neutron-fwaas `_ +* `openstack/neutron-lbaas `_ +* `openstack/neutron-vpnaas `_ +* `openstack/python-neutronclient `_ +* `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 `_. +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 `_ +* `60 day review stats `_ +* `90 day review stats `_ +* `180 day review stats `_ + +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. diff --git a/doc/source/policies/gate-failure-triage.rst b/doc/source/policies/gate-failure-triage.rst new file mode 100644 index 00000000000..db757b04959 --- /dev/null +++ b/doc/source/policies/gate-failure-triage.rst @@ -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 `_ +* `logstash `_ + +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 `_ +(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 `_ 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 `_ +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 `_ page has all the current open ER queries. +To file one, please see the `ER Wiki `_. diff --git a/doc/source/policies/index.rst b/doc/source/policies/index.rst new file mode 100644 index 00000000000..9a780eeb56e --- /dev/null +++ b/doc/source/policies/index.rst @@ -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`