Browse Source

Update the documentation link for doc migration

* Update the URLs affected by the doc-migration
  (/developer/<project>/ to <project>/latest/)
* Follow content rearrangement
* Convert links to local documents into :doc: or :ref:
* Use https instead of http for the updated links on

Part of the doc-migration work.

Change-Id: I62e317d9198f175a43d73bbfd419b6878de90d5a
Akihiro Motoki 5 years ago
  1. 2
  2. 4
  3. 2
  4. 2
  5. 4
  6. 3
  7. 4
  8. 4
  9. 2
  10. 23
  11. 14
  12. 1
  13. 2
  14. 2
  15. 4
  16. 2
  17. 2
  18. 2
  19. 11
  20. 8
  21. 2
  22. 8
  23. 2
  24. 6
  25. 27
  26. 2
  27. 6
  28. 2
  29. 4
  30. 2
  31. 2
  32. 2
  33. 2


@ -1,7 +1,7 @@
If you would like to contribute to the development of OpenStack Networking,
you must follow the steps documented at:
Pull requests submitted through GitHub will be ignored.


@ -2,14 +2,14 @@ Neutron Style Commandments
- Step 1: Read the OpenStack Style Commandments
- Step 2: Read on
Neutron Specific Commandments
Some rules are enforced by `neutron-lib hacking factory
while other rules are specific to Neutron repository.
Below you can find a list of checks specific to this repository.


@ -381,7 +381,7 @@ Scenario Tests
Scenario tests (neutron/tests/tempest/scenario), like API tests, use the
Tempest test infrastructure and have the same requirements. Guidelines for
writing a good scenario test may be found at the Tempest developer guide:
Scenario tests, like API tests, are split between the Tempest and Neutron
repositories according to the Neutron API the test is targeting.


@ -33,7 +33,7 @@ Networking API call has a corresponding :command:`neutron` command.
The :command:`openstack` CLI is a common interface for all OpenStack
projects, however, not every API operation has been implemented. For the
list of available commands, see `Command List
The :command:`neutron` CLI includes a number of options. For details, see
`Create and manage networks <>`__.


@ -15,7 +15,7 @@ There are two reference implementations of LBaaS v2.
The one is an agent based implementation with HAProxy.
The agents handle the HAProxy configuration and manage the HAProxy daemon.
Another LBaaS v2 implementation, `Octavia
<>`_, has a separate API and
<>`_, has a separate API and
separate worker processes that build load balancers within virtual machines on
hypervisors that are managed by the Compute service. You do not need an agent
for Octavia.
@ -141,7 +141,7 @@ The `Hands on Lab - Install and Configure OpenStack Octavia
session at the OpenStack Summit in Tokyo provides an overview of Octavia.
The DevStack documentation offers a `simple method to deploy Octavia
and test the service with redundant load balancer instances. If you already
have Octavia installed and configured within your environment, you can
configure the Network service to use Octavia:


@ -45,8 +45,7 @@ node. For more information, see the
installation guide (select an appropriate OVS version in the
:guilabel:`Branch` drop-down menu).
`Neutron configuration reference for OVS-DPDK
for configuration of neutron OVS agent.
In case you wish to configure multiqueue, see the


@ -50,6 +50,6 @@ Enable the native OVS firewall driver
firewall_driver = openvswitch
For more information, see the `Open vSwitch Firewall Driver
For more information, see the
and the `video <>`_.


@ -64,8 +64,8 @@ path rendering.
.. image:: figures/port-chain-diagram.png
:alt: Port chain model
See the `developer documentation
<>`_ for more information.
See the `networking-sfc documentation
<>`_ for more information.


@ -28,4 +28,4 @@ The client command extension adds support for extending the neutron client while
considering ease of creation.
The full document can be found in the python-neutronclient repository:


@ -89,8 +89,7 @@ and examples below. We'll describe best practices for:
* Documentation;
Once you have everything in place you may want to add your project to the list
of Neutron sub-projects. See `Adding or removing projects to the stadium
of Neutron sub-projects. See :ref:`add-remove-projects-to-stadium`
for details.
@ -109,16 +108,15 @@ automatically provided. Contributors should follow the review guidelines
similar to those of Neutron. However, you as the maintainer have the
flexibility to choose who can approve/merge changes in your own repo.
It is recommended (but not required, see `policies
It is recommended (but not required,
see :doc:`policies <policies/thirdparty-ci>`)
that you set up a third-party CI system. This will provide a vehicle for
checking the third-party code against Neutron changes. See `Testing and
Continuous Integration`_ below for more detailed recommendations.
Design documents can still be supplied in form of Restructured Text (RST)
documents, within the same third-party library repo. If changes to the common
Neutron code are required, an `RFE
Neutron code are required, an :ref:`RFE <request-for-feature-enhancement>`
may need to be filed. However, every case is different and you are invited to
seek guidance from Neutron core reviewers about what steps to follow.
@ -262,7 +260,7 @@ driver.
If you are contributing a new plugin, the approach to choose should be based on
`Extras.d Hooks' externally hosted plugins
With the extra.d hooks, the DevStack integration is co-located with the
third-party integration library, and it leads to the greatest level of
flexibility when dealing with DevStack based dev/test deployments.
@ -339,7 +337,7 @@ oslo.i18n
* Each subproject repository should have its own oslo.i18n integration
wrapper module ``${MODULE_NAME}/``. The detail is found at
.. note::
@ -486,11 +484,10 @@ directory as an entrypoint in the ``neutron.db.alembic_migrations`` group::
DB Model/Migration Testing
Here is a `template functional test
<>`_ third-party
maintainers can use to develop tests for model-vs-migration sync in their
repos. It is recommended that each third-party CI sets up such a test, and runs
it regularly against Neutron master.
Here is a :doc:`template functional test <testing/template_model_sync_test>`
third-party maintainers can use to develop tests for model-vs-migration sync in
their repos. It is recommended that each third-party CI sets up such a test,
and runs it regularly against Neutron master.
Entry Points


@ -214,8 +214,8 @@ and interacting with linux utils.
tool, check if common platforms ship packages with the aforementioned
feature. Also, tag such a patch with ``UpgradeImpact`` to raise its
visibility (as these patches are brought up to the attention of the core team
during team meetings). More details in `review guidelines
during team meetings).
More details in :ref:`review guidelines <spec-review-practices>`.
* When a patch or the code depends on a new feature in the kernel or in any platform tools
(dnsmasq, ip, Open vSwitch etc.), consider introducing a new sanity check to
validate deployments for the expected features. Note that sanity checks *must
@ -301,9 +301,9 @@ Deprecation
Sometimes we want to refactor things in a non-backward compatible way. In most
cases you can use `debtcollector
<>`_ to mark things for
<>`_ to mark things for
deprecation. Config items have `deprecation options supported by oslo.config
The deprecation process must follow the `standard deprecation requirements
@ -312,7 +312,7 @@ In terms of neutron development, this means:
* A launchpad bug to track the deprecation.
* A patch to mark the deprecated items. If the deprecation affects
users (config items, API changes) then a `release note
<>`_ must be
<>`_ must be
* Wait at least one cycle and at least three months linear time.
* A patch that removes the deprecated items. Make sure to refer to the
@ -334,7 +334,7 @@ Document common pitfalls as well as good practices done when instrumenting your
to avoid littering the logs with traces logged at inappropriate levels.
* The logger should only be passed unicode values. For example, do not pass it
exceptions or other objects directly (LOG.error(exc), LOG.error(port), etc.).
for more details.
* Don't pass exceptions into LOG.exception: it is already implicitly included
in the log message by Python logging module.
@ -450,7 +450,7 @@ IRC
and send public questions to the channel rather then to a specific person if possible.
(This increase the chances of getting faster answers to your questions).
A list of the areas and lieutenants nicknames can be found at
`Core Reviewers <>`_.
:doc:`Core Reviewers <policies/neutron-teams>`.
Commit messages


@ -52,6 +52,7 @@ Database migrations
For details on the neutron-db-manage wrapper and alembic migrations, see
`Alembic Migrations <alembic_migrations.html>`_.
.. _testing-database-migrations:
Tests to verify that database migrations and models are in sync


@ -20,7 +20,7 @@ external DNS service. This interface is based on an abstract driver that can be
used as the base class to implement concrete drivers to interact with various
DNS services. The reference implementation of such a driver integrates neutron
`OpenStack Designate <>`_.
`OpenStack Designate <>`_.
This integration allows users to publish *dns_name* and *dns_domain*
attributes associated with floating IP addresses, ports, and networks in an


@ -25,7 +25,7 @@ Neutron Stadium i18n
* Refer to oslo_i18n documentation for the general mechanisms that should
be used:
be used:
* Each stadium project should NOT consume _i18n module from neutron-lib
or neutron.


@ -41,7 +41,7 @@ dictionary messages by defining a strict structure and keeping strong typing.
Because of it, you can be sure of what is sent and how to use the data on the
receiving end.
.. _Oslo VersionedObjects:
.. _Oslo VersionedObjects:
Usage of objects
@ -635,6 +635,6 @@ References
.. [#]
.. [#]
.. [#]
.. [#]
.. [#]
.. [#]
.. [#]


@ -296,7 +296,7 @@ References
.. [#] `Oslo policy module <>`_
.. [#] `Oslo policy developer <documentation:>`_
.. [#] `Oslo policy developer <>`_
.. [#] API controller item_ method
.. _item:


@ -196,4 +196,4 @@ More Info
For more information, see the oslo.messaging documentation:


@ -27,7 +27,7 @@ Neutron Messaging Callback System
Neutron already has a `callback system
for in-process resource callbacks where publishers and subscribers are
able to publish and subscribe for resource events.


@ -27,9 +27,11 @@ repository is only meant for specs from Neutron itself, and the advanced
services repositories as well. This includes FWaaS, LBaaS, and VPNaaS. Other
sub-projects are encouraged to fold their specs into their own devref code
in their sub-project gerrit repositories. Please see additional comments
in the Neutron teams `section <>`_
in the Neutron teams :ref:`section <specs-core-reviewer-team>`
for reviewer requirements of the neutron-specs repository.
.. _request-for-feature-enhancement:
Neutron Request for Feature Enhancements
@ -261,10 +263,9 @@ Documentation
The above process involves two places where any given feature can start to be
documented - namely in the RFE bug, and in the spec - and in addition to those
Neutron has a substantial `developer reference guide
<>`_ (aka
'devref'), and user-facing docs such as the `networking guide
<>`_. So it might be asked:
Neutron has a substantial :doc:`developer reference guide </contributor/index>`
(aka 'devref'), and user-facing docs such as
the :doc:`networking guide </admin/index>`. So it might be asked:
* What is the relationship between all of those?


@ -137,8 +137,8 @@ It's also worth adding that some of these projects are part of the so
called Neutron `stadium <>`_.
Because of that, their release is managed centrally by the Neutron
release team; requests for releases need to be funnelled and screened
properly before they can happen. Release request process is described `here
properly before they can happen. Release request process is described
:ref:`here <guideline-releases>`.
.. _guidelines:
@ -263,7 +263,7 @@ If the bug report is sound, move next:
* Depending on ease of reproduction (or if the issue can be spotted in the
code), mark it as 'Confirmed'. If you are unable to assess/triage the
issue because you do not have access to a repro environment, consider
reaching out the `Lieutenant <>`_,
reaching out the :ref:`Lieutenant <core-review-hierarchy>`,
go-to person for the affected component;
he/she may be able to help: assign the bug to him/her for further
screening. If the bug already has an assignee, check that a patch is
@ -348,7 +348,7 @@ Proposing New Tags
New tags, or changes in the meaning of existing tags (or deletion), are to be
proposed via patch to this section. After discussion, and approval, a member of
the bug team will create/delete the tag in Launchpad. Each tag covers an area
with an identified go-to contact or `Lieutenant <>`_,
with an identified go-to contact or :ref:`Lieutenant <core-review-hierarchy>`,
who can provide further insight. Bug queries are provided below for convenience,
more will be added over time if needed.


@ -59,6 +59,8 @@ In addition to that, the following rules are to follow:
that would help interested parties to identify their platform limitation
in timely manner.
.. _spec-review-practices:
Neutron Spec Review Practices
In addition to code reviews, Neutron also maintains a BP specification git repository. Detailed


@ -42,6 +42,8 @@ error causing job failures end up here. It should be duty of the diligent Neutro
classification rate for neutron jobs is as close as possible to 100%. To this aim, the diligent Neutron
developer should adopt the procedure outlined in the following sections.
.. _troubleshooting-tempest-jobs:
Troubleshooting Tempest jobs
1. Open logs for failed jobs and look for logs/testr_results.html.gz.
@ -52,7 +54,7 @@ Troubleshooting Tempest jobs
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 an `Elastic Recheck Query <>`_ for it.
5. File a bug for this failure, and push an :ref:`Elastic Recheck Query <elastic-recheck-query>` for it.
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.
@ -68,12 +70,14 @@ Troubleshooting functional/fullstack job
forget to put a snippet of the trace into the new launchpad bug. If the
log file for a particular job doesn't contain any trace, pick the one
from testr_results.html.gz.
5. Create an `Elastic Recheck Query <>`_
5. Create an :ref:`Elastic Recheck Query <elastic-recheck-query>`
Root Causing a Gate Failure
Time-based identification, i.e. find the naughty patch by log scavenging.
.. _elastic-recheck-query:
Filing An Elastic Recheck Query
The `elastic recheck <>`_ page has all the current open ER queries.


@ -22,5 +22,5 @@ For example, do not just put an empty "recheck" comment but find the related
bug number and put a "recheck bug ######" comment instead. If a bug does not
exist yet, create one so other team members can have a look. It helps us
maintain better visibility of gate failures. You can find how to troubleshoot
gate failures in the `Gate Failure Triage <>`_
gate failures in the :ref:`Gate Failure Triage <troubleshooting-tempest-jobs>`


@ -29,6 +29,8 @@ In essence, core reviewers share the following common ideals:
A core reviewer's responsibility doesn't end up with merging code. The above
lists are adding context around these responsibilities.
.. _core-review-hierarchy:
Core Review Hierarchy
@ -191,6 +193,8 @@ they choose to use them. However, by choosing to be a part of the Neutron
project, they submit to oversight and veto by the Neutron PTL if any issues
.. _specs-core-reviewer-team:
Neutron Specs Core Reviewer Team
Neutron `specs core reviewers <,members>`_
@ -220,7 +224,7 @@ the group of people who have full rights to the specs repo. This team, which mat
instituted to ensure a consistent architectural vision for the Neutron project, and
to continue to disaggregate and share the responsibilities of the Neutron PTL.
The team is in charge of reviewing and commenting on
`RFEs <>`_,
:ref:`RFEs <request-for-feature-enhancement>`,
and working with specification contributors to provide guidance on the process
that govern contributions to the Neutron project as a whole. The team
`meets regularly <>`_


@ -78,8 +78,8 @@ 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 <>`_,
`user/operator <>`_
:doc:`developer </contributor/index>`,
:doc:`user/operator </admin/index>`
and `API <>`_
documentations available.
@ -99,14 +99,14 @@ mature OpenStack projects:
More Database related information can be found on:
* :doc:`/contributor/alembic_migrations`
* :doc:`/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 <>`_.
:doc:`Neutron testing documentation </contributor/testing/testing>`.
* Good release footprint, according to the chosen `release model <>`_.
@ -117,7 +117,7 @@ mature OpenStack projects:
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 <>`_.
* 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
@ -140,6 +140,8 @@ consideration:
interface to support multiple backend technologies, and/or adopt the
flavor framework as necessary.
.. _add-remove-projects-to-stadium:
Adding or removing projects to the Stadium
@ -171,7 +173,8 @@ 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 <>`_,
Once a project is included, it abides by the Neutron
:doc:`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
@ -180,10 +183,10 @@ Checklist
* How to integrate documentation into docs.o.o: The documentation
website has a section for `project developer documentation <>`_.
website has a section for `project developer documentation <>`_.
Each project in the Neutron Stadium must have an entry under the
'Networking Sub Projects' section that points to the developer
documentation for the project, available at<your-project>/.
documentation for the project, available at ``<your-project>/latest/``.
This is a two step process that involves the following:
* Build the artefacts: this can be done by following example
@ -260,7 +263,7 @@ Checklist
For release documentation related to Neutron, please check the
`Neutron policies document <>`_.
Once, everything is set up and your project is released, make sure
you see an entry on the release page (e.g. `Ocata <>`_.
Make sure you release according to the project declared release
@ -280,8 +283,8 @@ Checklist
More information on how to develop python-openstackclient plugins
can be found on the following links:
It is worth prefixing the commands being added with the keyword
`network <>`_ to


@ -122,6 +122,8 @@ following the stable branch policies as defined by on the `Stable Branch wiki
means that, among other things, no features are allowed to be backported into
stable branches.
.. _guideline-releases:


@ -34,14 +34,12 @@ What does the test do?
This test compares models with the result of existing migrations. It is based on
which is provided by oslo.db and was adapted for Neutron. It compares core
Neutron models and vendor specific models with migrations from Neutron core and
migrations from the driver/plugin repo. This test is functional - it runs against
MySQL and PostgreSQL dialects. The detailed description of this test can be
found in Neutron Database Layer section - `Tests to verify that database
migrations and models are in sync
found in Neutron Database Layer section - :ref:`testing-database-migrations`.
Steps for implementing the test


@ -40,7 +40,7 @@ def safe_creation(context, create_fn, delete_fn, create_bindings,
More information when this method could be used can be found in
developer guide - Effective Neutron: Database interaction section.
:param context: context


@ -1,4 +1,4 @@
See doc/source/devref/alembic_migrations.rst
See doc/source/contributor/alembic_migrations.rst
Rendered at


@ -24,7 +24,7 @@ depends_on = ('89ab9a816d70',)
# therefore the following column addition ( which should have been in an
# expand phase ) is also submitted in the contract phase. For information
# about the expand and contract scripts and how the depends_on works, please
# refer <
# refer <
# alembic_migrations.html#expand-and-contract-scripts>
from alembic import op


@ -8,7 +8,7 @@ features:
named 'trunk' must be added to the option ``service_plugins`` in your
neutron.conf. The plugin exposes two new extensions ``trunk`` and
``trunk_details``. The plugin can work with multiple backends and in
particular Neutron has support for `ML2/openvswitch <>`_
particular Neutron has support for `ML2/openvswitch <>`_
and ML2/linuxbridge.
Even though Neutron API compatibility should be preserved for ports
associated to trunks, since this is the first release where the feature


@ -7,4 +7,4 @@ OpenStack projects. Background on the process, tooling, and
methodology is documented in a `mailing list post by Doug Hellmann <>`_.
For information on how to create release notes, please consult the
`Release Notes documentation <>`_.
`Release Notes documentation <>`_.


@ -5,7 +5,7 @@ description-file =
author = OpenStack
author-email =
home-page =
home-page =
classifier =
Environment :: OpenStack
Intended Audience :: Information Technology