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

@@ -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.

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 <http://codesearch.openstack.org/?q=neutron-lib-current&i=nope&files=requirements.txt&repos=>`_
+  should also be updated as part of consumption.
 
 Examples:
 

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