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

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.

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 sub-project owner proposes a patch to openstack/releases repository with the intended git hash. The Neutron release liaison should be added in Gerrit to the list of reviewers for the patch.
  • If the subproject is not managed by OpenStack Release Team, a member of neutron-release tags the release and creates the needed stable branches, if needed. Note: tagging will release the code to PyPI. Note: new major tag versions should conform to SemVer requirements, meaning no year numbers should be used as a major version. The switch to SemVer is advised at earliest convenience for all new major releases.
  • The Neutron release liaison votes with +1 for the openstack/releases patch that gives indication to release team the patch is ready to merge.
  • 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. [1]
  • 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.

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:

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