openstack/neutron-lib
Code Issues Proposed changes

doc neutron-lib current

Browse Source 
This patch updates the docs to explain the use of neutron-lib-current
[1] and consumption in general.

[1] http://lists.openstack.org/pipermail/openstack-dev/2018-September/135063.html

Change-Id: I2e0dfb6ad34b1060c22945d01e22c589d42e27c7
This commit is contained in:
Boden R 2019-01-16 11:50:01 -07:00
parent 872c554c8e
commit c0f55acf70
3 changed files with 33 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
doc/source/contributor/consuming.rst Normal file
View File

@ -0,0 +1,30 @@
=====================
Consuming neutron-lib
=====================
Many OpenStack projects consume neutron-lib by importing and using its code.
As a result, these consumers must define ``neutron-lib`` as a dependency in their
respective ``requirements.txt`` file. While this is likely nothing new to most
OpenStack developers, it may not be obvious to consumers if they need to always
use the latest release of neutron-lib, or if they can lag behind using an
old(er) release of it.
The answer is that it's up to the consuming project if they want to stay
"current" or not in terms of the neutron-lib version they use. While we might
like all consumers to stay current and there are benefits to it, this isn't
always realistic for projects that have less developers/velocity. Therefore,
each project has two options for consuming neutron-lib.
* Opt-in to stay current by adding a comment with ``neutron-lib-current`` in
their ``requirements.txt``. This string declares the project's intent to use
the latest version of neutron-lib as well as their agreement to stay current
with overall OpenStack initiatives. These projects receive updates "for free"
as part of the ongoing neutron-lib work. For more details see the
`ML archive <http://lists.openstack.org/pipermail/openstack-dev/2018-September/135063.html>`_
* Do not opt-in and rather manage your own consumption of neutron-lib. In this
case your project developers must define the version of neutron-lib to use
and update the project's code to consume it as they bump up the version. In
this scenario most projects will also be managing a back-leveled version of
``neutron`` since neutron is always current with neutron-lib and might otherwise
break the consuming code.

2
doc/source/contributor/contributing.rst
View File

@ -148,6 +148,8 @@ source.
still has direct neutron imports). The check happens daily therefore consider waiting to
approve if you are either aware of another impactful change recently merged that has not
been yet processed or you see failure rates spiking.
- All projects that have `neutron-lib-current <http://codesearch.openstack.org/?q=neutron-lib-current&i=nope&files=requirements.txt&repos=>`_
should also be updated as part of consumption.
Examples:

1
doc/source/contributor/index.rst
View File

@ -29,6 +29,7 @@ components and in how to use them, from a development standpoint.
.. toctree::
:maxdepth: 2
consuming
conventions
review-guidelines
contributing