Neutron/VendorSplitPackaging

Neutron Vendor split: Packager perspective
Neutron has started on the route towards splitting vendor libraries from its tree into separate, vendor governed, repositories. Now vendors are in charge of releasing python (pypi) packages to the public to consume. Recent observations show that in some cases python packages released by vendors are not optimal for distribution consumption. Below you can see some random notes on how to help packagers to do their work by enhancing vendor library package contents.

Oslo modules
Neutron maintains some of oslo modules copied from oslo-incubator in neutron.openstack.common.* namespace. The tree is not supposed to be used by any code outside neutron core and *aas repositories. That said, multiple (if not most) vendor libraries still rely on the code in the tree.

The solution from vendor side would be one of the following:
 * stop using neutron.openstack.common.* modules and instead maintain the needed modules inside the vendor library. More details in the corresponding oslo policy.
 * switch to using oslo.* libraries that are graduating from oslo-incubator.
 * pinning neutron revision in requirements.txt to avoid breakages at random time. Note that in this case vendors should also make sure they update the pin quite frequently to keep up with neutron development. Note that revision pinning has its own benefits beyond oslo modules' consumption.

PyPI package contents
It's observed that some vendor libraries already released at PyPI miss some files that are present in corresponding git repositories, and are useful for packaging. Specifically, the following files should be present in PyPI packages to help packagers:
 * requirements.txt and test-requirements.txt: used to refer to dependencies that vendors expect to be used with their libraries.
 * LICENSE file: most distributions have a requirement that license text must be included in their packages.
 * all files needed to run tests without virtualenv: packages may run unit tests as part of their build process.

Dependencies

 * Dependencies are communicated to packagers via requirements.txt and test-requirements.txt, so those files should contain proper and full dependencies that are needed in runtime and when running unit tests. It's adviced that vendor libraries do not rely on neutron dependency to fetch all the needed dependencies for them, and instead put packages that are explicitly used in their code into those files. The rationale behind it is that neutron may drop some of those dependencies later, and vendor libraries will become broken.
 * Be sure that your dependencies fit with the dependencies listed in the requirements repository (see global-requirements.txt and test-requirements.txt) for the OpenStack version you want to support (i.e. for Kilo, use the dependencies from the Kilo branch in that repository). That is important to avoid conflicts between the overall OpenStack requirements and the requirements for your project and makes life for distributions much easier. Note that you may also add your stackforge project to projects.txt file to get automatic updates to your requirements.

Git repository
It's also advised that vendor libraries maintain a public git repository with the code in addition to PyPI releases. It's useful in cases where distributions run packaging CI against master (for reference, RDO for master called Delorean does it).