This document provides guidance for those who maintain projects that consume main neutron or neutron advanced services repositories as a dependency. It is not meant to describe projects that are not tightly coupled with Neutron code.
At all times, avoid using any Neutron symbols that are explicitly marked as private (those have an underscore at the start of their names).
Try to avoid copy pasting the code from Neutron to extend it. Instead, rely on enormous number of different plugin entry points provided by Neutron (L2 agent extensions, API extensions, service plugins, core plugins, ML2 mechanism drivers, etc.)
Subprojects usually depend on neutron repositories, by using -e git://... schema to define such a dependency. The dependency must not be present in requirements lists though, and instead belongs to tox.ini deps section. This is because next pbr library releases do not guarantee -e git://... dependencies will work.
You may still put some versioned neutron dependency in your requirements list to indicate the dependency for anyone who packages your subproject.
Each neutron project maintains its own lists of requirements. Subprojects that depend on neutron while directly using some of those libraries that neutron maintains as its dependencies must not rely on the fact that neutron will pull the needed dependencies for them. Direct library usage requires that this library is mentioned in requirements lists of the subproject.
The reason to duplicate those dependencies is that neutron team does not stick to any backwards compatibility strategy in regards to requirements lists, and is free to drop any of those dependencies at any time, breaking anyone who could rely on those libraries to be pulled by neutron itself.
At all times, subprojects that use neutron as a dependency should make sure their dependencies do not conflict with neutron’s ones.
Core neutron projects maintain their requirements lists by utilizing a so-called proposal bot. To keep your subproject in sync with neutron, it is highly recommended that you register your project in openstack/requirements:projects.txt file to enable the bot to update requirements for you.
Once a subproject opts in global requirements synchronization, it should enable check-requirements jobs in project-config. For example, see this patch.
Stable branches for subprojects should be created at the same time when corresponding neutron stable branches are created. This is to avoid situations when a postponed cut-off results in a stable branch that contains some patches that belong to the next release. This would require reverting patches, and this is something you should avoid.
Make sure your neutron dependency uses corresponding stable branch for neutron, not master.
Note that to keep requirements in sync with core neutron repositories in stable branches, you should make sure that your project is registered in openstack/requirements:projects.txt for the branch in question.
Subproject stable branches are supervised by horizontal neutron-stable-maint team.
More info on stable branch process can be found on the following page.
Merges into stable branches are handled by members of the neutron-stable-maint gerrit group. The reason for this is to ensure consistency among stable branches, and compliance with policies for stable backports.
For sub-projects who participate in the Neutron Stadium effort and who also create and utilize stable branches, there is an expectation around what is allowed to be merged in these stable branches. The Stadium projects should be following the stable branch policies as defined by on the Stable Branch wiki. This means that, among other things, no features are allowed to be backported into stable branches.
It is suggested that sub-projects release new tarballs on PyPI from time to time, especially for stable branches. It will make the life of packagers and other consumers of your code easier.
It is highly suggested that you do not strip pieces of the source tree (tests, executables, tools) before releasing on PyPI: those missing pieces may be needed to validate the package, or make the packaging easier or more complete. As a rule of thumb, don’t strip anything from the source tree unless completely needed.
Only members of the neutron-release gerrit group can do the following release related tasks:
Make sure you talk to a member of neutron-release to perform these tasks.
To release a sub-project, follow the following steps:
Note
You need to be careful when picking a git commit to base new releases on. In most cases, you’ll want to tag the merge commit that merges your last commit in to the branch. This bug shows an instance where this mistake was caught. Notice the difference between the incorrect commit and the correct one which is the merge commit. git log 6191994..22dd683 --oneline shows that the first one misses a handful of important commits that the second one catches. This is the nature of merging to master.
To make a branch end of life, follow the following steps: