rearrange content to fit the new standard layout
Part of doc-migration work The proposed document strucutre is documented at: http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html Change-Id: Idea4f21bb66fbdf4b4f8925f2260f43374a108f3
This commit is contained in:
parent
94d7e681ee
commit
b9f62ba6a3
|
@ -1,17 +1,14 @@
|
|||
If you would like to contribute to the development of OpenStack, you must
|
||||
follow the steps in this page:
|
||||
|
||||
http://docs.openstack.org/infra/manual/developers.html
|
||||
http://docs.openstack.org/infra/manual/developers.html
|
||||
|
||||
If you already have a good understanding of how the system works and your
|
||||
OpenStack accounts are set up, you can skip to the development workflow
|
||||
section of this documentation to learn how changes to OpenStack should be
|
||||
submitted for review via the Gerrit tool:
|
||||
|
||||
http://docs.openstack.org/infra/manual/developers.html#development-workflow
|
||||
http://docs.openstack.org/infra/manual/developers.html#development-workflow
|
||||
|
||||
Pull requests submitted through GitHub will be ignored.
|
||||
|
||||
Bugs should be filed on Launchpad, not GitHub:
|
||||
|
||||
https://bugs.launchpad.net/neutron-lib
|
||||
https://bugs.launchpad.net/neutron-lib
|
||||
|
|
|
@ -1,7 +1,8 @@
|
|||
============
|
||||
Contributing
|
||||
============
|
||||
.. include:: ../../CONTRIBUTING.rst
|
||||
|
||||
.. include:: ../../../CONTRIBUTING.rst
|
||||
|
||||
As your code is subject to the `review guidelines <./review-guidelines.html>`_,
|
||||
please take the time to familiarize yourself with those guidelines.
|
||||
|
@ -25,50 +26,50 @@ The rehoming workflow procedure has four main phases:
|
|||
Phase 1: Rehome
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
#. Identify the chunk of code for rehoming. Applicable code includes common
|
||||
classes/functions/modules/etc. that are consumed by networking project(s) outside of
|
||||
neutron. Optimal consumption patterns of the code at hand must also be considered to
|
||||
ensure the rehomed code addresses any technical debt. Finally, leave low-hanging
|
||||
fruit for last and tackle the most commonly used code first. If you have any doubt
|
||||
about the applicability of code for rehoming, reach out to one of the neutron core
|
||||
developers before digging in.
|
||||
#. Identify the chunk of code for rehoming. Applicable code includes common
|
||||
classes/functions/modules/etc. that are consumed by networking project(s) outside of
|
||||
neutron. Optimal consumption patterns of the code at hand must also be considered to
|
||||
ensure the rehomed code addresses any technical debt. Finally, leave low-hanging
|
||||
fruit for last and tackle the most commonly used code first. If you have any doubt
|
||||
about the applicability of code for rehoming, reach out to one of the neutron core
|
||||
developers before digging in.
|
||||
|
||||
#. Find and identify any unit tests for the code being rehomed. These unit tests
|
||||
can often be moved into neutron-lib with minimal effort. After inspecting the
|
||||
applicable unit tests, rewrite any that are non-optimal.
|
||||
#. Find and identify any unit tests for the code being rehomed. These unit tests
|
||||
can often be moved into neutron-lib with minimal effort. After inspecting the
|
||||
applicable unit tests, rewrite any that are non-optimal.
|
||||
|
||||
#. Search and understand the consumers of the code being rehomed. This must include other
|
||||
networking projects in addition to neutron itself. At this point it may be determined
|
||||
that the code should be refactored before it is consumed. There are a few common
|
||||
strategies for refactoring, and the one chosen will depend on the nature of the code
|
||||
at hand:
|
||||
#. Search and understand the consumers of the code being rehomed. This must include other
|
||||
networking projects in addition to neutron itself. At this point it may be determined
|
||||
that the code should be refactored before it is consumed. There are a few common
|
||||
strategies for refactoring, and the one chosen will depend on the nature of the code
|
||||
at hand:
|
||||
|
||||
- Refactor/enhance the code as part of the initial neutron-lib patch. If this change
|
||||
will be disruptive to consumers, clearly communicate the change via email list or
|
||||
`meeting topic <https://wiki.openstack.org/wiki/Network/Meetings#Neutron-lib_and_planned_neutron_refactoring>`_.
|
||||
- Leave the refactoring to the next (Enhance) phase. In this rehome phase, copy the code
|
||||
as-is into a private module according to our `conventions <./conventions.html>`_. This
|
||||
approach is slower, but may be necessary in some cases.
|
||||
- Refactor/enhance the code as part of the initial neutron-lib patch. If this change
|
||||
will be disruptive to consumers, clearly communicate the change via email list or
|
||||
`meeting topic <https://wiki.openstack.org/wiki/Network/Meetings#Neutron-lib_and_planned_neutron_refactoring>`_.
|
||||
- Leave the refactoring to the next (Enhance) phase. In this rehome phase, copy the code
|
||||
as-is into a private module according to our `conventions <./conventions.html>`_. This
|
||||
approach is slower, but may be necessary in some cases.
|
||||
|
||||
#. Understand existing work underway which may impact the rehomed code, for example,
|
||||
in-flight patch sets that update the code being rehomed. In some cases it may make
|
||||
sense to let the in-flight patch merge and solidify a bit before rehoming.
|
||||
#. Understand existing work underway which may impact the rehomed code, for example,
|
||||
in-flight patch sets that update the code being rehomed. In some cases it may make
|
||||
sense to let the in-flight patch merge and solidify a bit before rehoming.
|
||||
|
||||
#. Prepare the code for neutron-lib. This may require replacing existing imports
|
||||
with those provided by neutron-lib and/or rewriting/rearchitecting non-optimal
|
||||
code (see above). The interfaces in the rehomed code are subject to our
|
||||
`conventions <./conventions.html>`_.
|
||||
#. Prepare the code for neutron-lib. This may require replacing existing imports
|
||||
with those provided by neutron-lib and/or rewriting/rearchitecting non-optimal
|
||||
code (see above). The interfaces in the rehomed code are subject to our
|
||||
`conventions <./conventions.html>`_.
|
||||
|
||||
#. Prepare the unit test code for neutron-lib. As indicated in the `review guidelines
|
||||
<./review-guidelines.html>`_ we are looking for a high code coverage by tests. This may
|
||||
require adding additional tests if neutron was lacking in coverage.
|
||||
#. Prepare the unit test code for neutron-lib. As indicated in the `review guidelines
|
||||
<./review-guidelines.html>`_ we are looking for a high code coverage by tests. This may
|
||||
require adding additional tests if neutron was lacking in coverage.
|
||||
|
||||
#. Submit and shepherd your patch through its neutron-lib review. Include a
|
||||
`release note <http://docs.openstack.org/developer/reno/>`_ that describes the code's
|
||||
old neutron location and new neutron-lib location. Also note that in some cases it makes
|
||||
sense to prototype a change in a consumer project to better understand the impacts of
|
||||
the change, which can be done using the ``Depends-On:`` approach described in the
|
||||
`review guidelines <./review-guidelines.html>`_
|
||||
#. Submit and shepherd your patch through its neutron-lib review. Include a
|
||||
`release note <http://docs.openstack.org/developer/reno/>`_ that describes the code's
|
||||
old neutron location and new neutron-lib location. Also note that in some cases it makes
|
||||
sense to prototype a change in a consumer project to better understand the impacts of
|
||||
the change, which can be done using the ``Depends-On:`` approach described in the
|
||||
`review guidelines <./review-guidelines.html>`_
|
||||
|
||||
Examples:
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
..
|
||||
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.
|
||||
|
||||
Convention for heading levels in Neutron lib devref:
|
||||
======= Heading 0 (reserved for the title in a document)
|
||||
------- Heading 1
|
||||
~~~~~~~ Heading 2
|
||||
+++++++ Heading 3
|
||||
''''''' Heading 4
|
||||
(Avoid deeper levels because they do not render well.)
|
||||
|
||||
|
||||
Contributor Guide
|
||||
=================
|
||||
|
||||
In the Contributor Guide, you will find information on the Neutron Library
|
||||
components and in how to use them, from a development standpoint.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
conventions
|
||||
review-guidelines
|
||||
contributing
|
||||
releasing
|
||||
internals
|
|
@ -19,16 +19,10 @@
|
|||
''''''' Heading 4
|
||||
(Avoid deeper levels because they do not render well.)
|
||||
|
||||
|
||||
Developer Guide
|
||||
===============
|
||||
|
||||
In the Developer Guide, you will find information on the Neutron Library
|
||||
components and in how to use them, from a development standpoint.
|
||||
|
||||
|
||||
=====================
|
||||
Neutron Lib Internals
|
||||
---------------------
|
||||
=====================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
|
@ -37,20 +31,3 @@ Neutron Lib Internals
|
|||
api_converters
|
||||
api_validators
|
||||
callbacks
|
||||
|
||||
|
||||
Module Reference
|
||||
----------------
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
.. todo::
|
||||
|
||||
Add in all the big modules as automodule indexes.
|
||||
|
||||
|
||||
Indices and tables
|
||||
------------------
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`search`
|
|
@ -11,8 +11,8 @@
|
|||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
Welcome to Neutron Lib developer documentation!
|
||||
===============================================
|
||||
Welcome to Neutron Lib documentation!
|
||||
=====================================
|
||||
|
||||
Neutron-lib is an OpenStack library project used by Neutron, Advanced Services,
|
||||
and third-party projects that aims to provide common functionality across all
|
||||
|
@ -39,24 +39,10 @@ The `Neutron Development wiki`_ is also a good resource for new contributors.
|
|||
|
||||
Enjoy!
|
||||
|
||||
|
||||
Programming HowTos and Tutorials
|
||||
--------------------------------
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
:maxdepth: 2
|
||||
|
||||
conventions
|
||||
installation
|
||||
usage
|
||||
review-guidelines
|
||||
contributing
|
||||
releasing
|
||||
|
||||
|
||||
Developer Docs
|
||||
==============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
devref/index
|
||||
install/index
|
||||
user/index
|
||||
contributor/index
|
||||
reference/index
|
||||
|
|
|
@ -0,0 +1,34 @@
|
|||
..
|
||||
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.
|
||||
|
||||
Convention for heading levels in Neutron lib devref:
|
||||
======= Heading 0 (reserved for the title in a document)
|
||||
------- Heading 1
|
||||
~~~~~~~ Heading 2
|
||||
+++++++ Heading 3
|
||||
''''''' Heading 4
|
||||
(Avoid deeper levels because they do not render well.)
|
||||
|
||||
================
|
||||
Module Reference
|
||||
================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
.. todo::
|
||||
|
||||
Add in all the big modules as automodule indexes.
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`search`
|
|
@ -1,14 +1,6 @@
|
|||
========
|
||||
Usage
|
||||
========
|
||||
|
||||
To use neutron-lib in a project::
|
||||
|
||||
import neutron_lib
|
||||
|
||||
|
||||
==============
|
||||
Hacking Checks
|
||||
--------------
|
||||
==============
|
||||
|
||||
The ``neutron_lib.hacking`` package implements a number of public
|
||||
`hacking checks <https://github.com/openstack-dev/hacking>`_ intended to help
|
|
@ -0,0 +1,8 @@
|
|||
=====
|
||||
Usage
|
||||
=====
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
hacking
|
Loading…
Reference in New Issue