openstack/neutron
Code Issues Proposed changes
c3b83a9ca6
neutron/doc/source/contributor/stadium/governance.rst
Boden R d538ea774b update static urls for pike 
A number of places in our docs have static links to ocata based content.
What's more some of our doc content lives at a new URL.

This patch updates our docs to ref pike rather than ocata.

This patch should be backported to pike.

Change-Id: Ieefaf7a78dce03faf9df1ca7d596bbd81230805b
Closes-Bug: #1714516
2017-09-01 12:37:13 -06:00

15 KiB
Raw Blame History

Stadium Governance

Background

Neutron grew to become a big monolithic codebase, and its core team had a tough time making progress on a number of fronts, like adding new features, ensuring stability, etc. During the Kilo timeframe, a decomposition effort started, where the codebase got disaggregated into separate repos, like the high level services, and the various third-party solutions for L2 and L3 services, and the Stadium was officially born.

These initiatives enabled the various individual teams in charge of the smaller projects the opportunity to iterate faster and reduce the time to feature. This has been due to the increased autonomy and implicit trust model that made the lack of oversight of the PTL and the Neutron drivers/core team acceptable for a small number of initiatives. When the proposed arrangement allowed projects to be automatically enlisted as a Neutron project based simply on description, and desire for affiliation, the number of projects included in the Stadium started to grow rapidly, which created a number of challenges for the PTL and the drivers team.

In fact, it became harder and harder to ensure consistency in the APIs, architecture, design, implementation and testing of the overarching project; all aspects of software development, like documentation, integration, release management, maintenance, and upgrades started to being neglected for some projects and that led to some unhappy experiences.

The point about uniform APIs is particularly important, because the Neutron platform is so flexible that a project can take a totally different turn in the way it exposes functionality, that it is virtually impossible for the PTL and the drivers team to ensure that good API design principles are being followed over time. In a situation where each project is on its own, that might be acceptable, but allowing independent API evolution while still under the Neutron umbrella is counterproductive.

These challenges led the Neutron team to find a better balance between autonomy and consistency and lay down criteria that more clearly identify when a project can be eligible for inclusion in the Neutron governance.

This document describes these criteria, and document the steps involved to maintain the integrity of the Stadium, and how to ensure this integrity be maintained over time when modifications to the governance are required.

When is a project considered part of the Stadium?

In order to be considered part of the Stadium, a project must show a track record of alignment with the Neutron core project. This means showing proof of adoption of practices as led by the Neutron core team. Some of these practices are typically already followed by the most mature OpenStack projects:

  • Exhaustive documentation: it is expected that each project will have a developer </contributor/index>, user/operator </admin/index> and API documentations available.

  • Exhaustive OpenStack CI coverage: unit, functional, and tempest coverage using OpenStack CI (upstream) resources so that Grafana and OpenStack Health support is available. Access to CI resources and historical data by the team is key to ensuring stability and robustness of a project. In particular, it is of paramount importance to ensure that DB models/migrations are tested functionally to prevent data inconsistency issues or unexpected DB logic errors due to schema/models mismatch. For more details, please look at the following resources:

    More Database related information can be found on:

    • /contributor/alembic_migrations
    • /contributor/internals/db_layer

    Bear in mind that many projects have been transitioning their codebase and tests to fully support Python 3+, and it is important that each Stadium project supports Python 3+ the same way Neutron core does. For more information on how to do testing, please refer to the Neutron testing documentation </contributor/testing/testing>.

  • Good release footprint, according to the chosen release model.

  • Adherence to deprecation and stable backports policies.

  • Demonstrated ability to do upgrades and/or rolling upgrades, where applicable. This means having grenade support on top of the CI coverage as described above.

  • Client bindings and CLI developed according to the OpenStack Client plugin model.

On top of the above mentioned criteria, the following also are taken into consideration:

  • A project must use, adopt and implement open software and technologies.
  • A project must integrate with Neutron via one of the supported, advertised and maintained public Python APIs. REST API does not qualify (the project python-neutronclient is an exception).
  • It adopts neutron-lib (with related hacking rules applied), and has proof of good decoupling from Neutron core internals.
  • It provides an API that adopts API guidelines as set by the Neutron core team, and that relies on an open implementation.
  • It adopts modular interfaces to provide networking services: this means that L2/7 services are provided in the form of ML2 mech drivers and service plugins respectively. A service plugin can expose a driver interface to support multiple backend technologies, and/or adopt the flavor framework as necessary.

Adding or removing projects to the Stadium

When a project is to be considered part of the Stadium, proof of compliance to the aforementioned practices will have to be demonstrated typically for at least two OpenStack releases. Application for inclusion is to be considered only within the first milestone of each OpenStack cycle, which is the time when the PTL and Neutron team do release planning, and have the most time available to discuss governance issues.

Projects part of the Neutron Stadium have typically the first milestone to get their house in order, during which time reassessment happens; if removed, because of substantial lack of meeting the criteria, a project cannot reapply within the same release cycle it has been evicted.

The process for proposing a repo into openstack/ and under the Neutron governance is to propose a patch to the openstack/governance repository. For example, to propose networking-foo, one would add the following entry under Neutron in reference/projects.yaml:

- repo: openstack/networking-foo
  tags:
    - name: release:independent

Typically this is a patch that the PTL, in collaboration with the project's point of contact, will shepherd through the review process. This step is undertaken once it is clear that all criteria are met. The next section provides an informal checklist that shows what steps a project needs to go through in order to enable the PTL and the TC to vote positively on the proposed inclusion.

Once a project is included, it abides by the Neutron RFE submission process </contributor/policies/blueprints>, where specifications to neutron-specs are required for major API as well as major architectural changes that may require core Neutron platform enhancements.

Checklist