.. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. Convention for heading levels in Neutron devref: ======= Heading 0 (reserved for the title in a document) ------- Heading 1 ~~~~~~~ Heading 2 +++++++ Heading 3 ''''''' Heading 4 (Avoid deeper levels because they do not render well.) Sub-Project Guidelines ====================== 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. Code Reuse ---------- 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.) Oslo Incubator ~~~~~~~~~~~~~~ Don't ever reuse neutron code that comes from oslo-incubator in your subprojects. For neutron repository, the code is usually located under the following path: neutron.openstack.common.* If you need any oslo-incubator code in your repository, copy it into your repository from oslo-incubator and then use it from there. Neutron team does not maintain any backwards compatibility strategy for the code subtree and can break anyone who relies on it at any time. Requirements ------------ Neutron dependency ~~~~~~~~~~~~~~~~~~ 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. Explicit dependencies ~~~~~~~~~~~~~~~~~~~~~ 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. Automated requirements updates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 --------------- 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 `_. Stable merge requirements ------------------------- 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. Releases -------- 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. Sub-Project Release Process ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Only members of the `neutron-release `_ gerrit group can do the following release related tasks: * Make releases * Create stable branches * Make stable branches end of life Make sure you talk to a member of neutron-release to perform these tasks. Follow the process found `here `_ for creating a bug for your request. To release a sub-project, follow the following steps: * For projects which have not moved to post-versioning, we need to push an alpha tag to avoid pbr complaining. A member of the neutron-release group will handle this. * A sub-project owner should modify setup.cfg to remove the version (if you have one), which moves your project to post-versioning, similar to all the other Neutron projects. You can skip this step if you don't have a version in setup.cfg. * A member of neutron-release will then `tag the release `_, which will release the code to PyPI. * The releases will now be on PyPI. A sub-project owner should verify this by going to an URL similar to `this `_. * A sub-project owner should next go to Launchpad and release this version using the "Release Now" button for the release itself. * If a sub-project uses the "delay-release" option, a sub-project owner should update any bugs that were fixed with this release to "Fix Released" in Launchpad. This step is not necessary if the sub-project uses the "direct-release" option, which is the default. [#jeepyb_release_options]_ * The new release will be available on `OpenStack Releases `_. * A sub-project owner should add the next milestone to the Launchpad series, or if a new series is required, create the new series and a new milestone. * Finally a sub-project owner should send an email to the openstack-announce mailing list announcing the new release. To make a branch end of life, follow the following steps: * A member of neutron-release will abandon all open change reviews on the branch. * A member of neutron-release will push an EOL tag on the branch. (eg. "icehouse-eol") * A sub-project owner should request the infrastructure team to delete the branch by sending an email to the infrastructure mailing list, not by bothering the infrastructure team on IRC. * A sub-project owner should tweak jenkins jobs in project-config if any. References ~~~~~~~~~~ .. [#jeepyb_release_options] http://lists.openstack.org/pipermail/openstack-dev/2015-December/081724.html