devref: added guidelines on how to maintain sub-projects

I was involved lately in several boring attempts to fix broken
sub-project requirements and stable branches, and I think part of the
problem here is that we don't communicate our expectations to
sub-projects clear enough.

This is a first attempt to set brief and clear guidelines to sub-project
maintainers on how to maintain their repositories without much hassle.

Change-Id: I9180ee530f96a885b5667e050d141ce0ab52a8ce

diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst
index 694f0f07eb283361de4ecce0cee984a9f65d0a67..1edbfd4f726b49a54937ff9ffd27dcc782d7edc7 100644 (file)
--- a/doc/source/devref/index.rst
+++ b/doc/source/devref/index.rst
@@ -43,6 +43,7 @@ Programming HowTos and Tutorials
     contribute
     neutron_api
     sub_projects
+    sub_project_guidelines
     client_command_extensions
     alembic_migrations
 

diff --git a/doc/source/devref/sub_project_guidelines.rst b/doc/source/devref/sub_project_guidelines.rst
new file mode 100644 (file)
index 0000000..1eecda9
--- /dev/null
+++ b/doc/source/devref/sub_project_guidelines.rst
@@ -0,0 +1,132 @@
+..
+      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).
+
+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
+<https://review.openstack.org/#/c/215671/>`_.
+
+Stable branches
+---------------
+
+Stable branches for libraries should be created at the same time when
+corresponding neutron stable branches are cut off. 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 <https://review.openstack.org/#/admin/groups/539,members>`_.
+
+More info on stable branch process can be found on `the following page
+<https://wiki.openstack.org/wiki/StableBranch>`_.
+
+Releases
+--------
+
+It is suggested that you release new subproject tarballs on PyPI from time to
+time, especially for stable branches. It will make life of packagers and other
+consumers of your code easier.
+
+Make sure you tag you release commits in git.
+
+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.
+
+TODO: fill in details on release process.

diff --git a/doc/source/devref/sub_projects.rst b/doc/source/devref/sub_projects.rst
index 92429e2ae4e537fa31f405b9dd21f08f1eea1db2..d1df015f117277c01c746dc175ec03303f70f3ab 100644 (file)
--- a/doc/source/devref/sub_projects.rst
+++ b/doc/source/devref/sub_projects.rst
@@ -67,6 +67,9 @@ working on testing.
 By being included, the project accepts oversight by the TC as a part of
 being in OpenStack, and also accepts oversight by the Neutron PTL.
 
+It is also assumed the respective review teams will make sure their projects
+stay in line with `current best practices <sub_project_guidelines.html>`_.
+
 Inclusion Criteria
 ------------------