From c0f55acf70597899a3905476fb96a673df7d35ce Mon Sep 17 00:00:00 2001 From: Boden R Date: Wed, 16 Jan 2019 11:50:01 -0700 Subject: [PATCH] doc neutron-lib current 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 --- doc/source/contributor/consuming.rst | 30 +++++++++++++++++++++++++ doc/source/contributor/contributing.rst | 2 ++ doc/source/contributor/index.rst | 1 + 3 files changed, 33 insertions(+) create mode 100644 doc/source/contributor/consuming.rst diff --git a/doc/source/contributor/consuming.rst b/doc/source/contributor/consuming.rst new file mode 100644 index 000000000..e6a686c42 --- /dev/null +++ b/doc/source/contributor/consuming.rst @@ -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 `_ + +* 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. diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst index d2dfde69a..02113b3e2 100644 --- a/doc/source/contributor/contributing.rst +++ b/doc/source/contributor/contributing.rst @@ -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 `_ + should also be updated as part of consumption. Examples: diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 9b4b4c9df..06481df04 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -29,6 +29,7 @@ components and in how to use them, from a development standpoint. .. toctree:: :maxdepth: 2 + consuming conventions review-guidelines contributing