diff --git a/specs/library-stable-branches.rst b/specs/library-stable-branches.rst new file mode 100644 index 0000000..bc8a348 --- /dev/null +++ b/specs/library-stable-branches.rst @@ -0,0 +1,190 @@ +======================================== + Managing Stable Branches for Libraries +======================================== + +Problem description +=================== + +We want to restrict stable branches to a narrow range of allowed +versions of all dependencies, to increase our chances of avoiding +breaking changes in the stable branches. + +This means rather than always rolling all library releases forward to +the most current release, we want to start using stable releases for +libraries more consistently. + +We also want to express the dependency range in a way that does not +require that we explicitly modify the allowed version when we produce +patch releases. So we want to place a cap on the upper bound of the +version range, rather than pinning to a specific version. + +The Oslo team has been considering this problem for a while, but we +now have more teams producing libraries, either server-support +libraries or clients, so we need to bring the plan to a wider audience +and apply a consistent set of procedures to all OpenStack libraries, +including Oslo, project-specific clients, the SDK, middleware, and any +other projects that are installed as subcomponents of the rest of +OpenStack. (The applications follow a stable branch process already, +so this process describes how to handle stable branches for projects +that are not applications.) + +All libraries should already be using the `pbr version of SemVer`_ for +version numbering. This lets us express a dependency within the range +of major.minor, and allow any patch release to meet the +requirement. This spec discusses the process for ensuring that we have +valid stable branches to work from. + +.. _pbr version of SemVer: http://docs.openstack.org/developer/pbr/semver.html + +Proposed change +=============== + +When we reach the feature freeze at the end of the cycle, libraries +should freeze development a little before the application freeze date +(Oslo freezes 1 week prior, which should be enough time for all +projects to follow these procedures). At that point, the release +manager for each library should follow the steps below, substituting +the release series name (for example, "kilo") for ``$SERIES``. + +#. Update the global requirements list to make the current version of + the library the minimum supported version, and express the + requirement using the "compatible version" operator (``~=``) to + allow for future patch releases (see the `Compatible Releases`_ + section of :pep:`440`). + + To avoid churn in the applications, we probably want to do this in + one, or at least just a very few, patches, so we will need to + coordinate between the release managers to get that set up. + +#. Create a ``stable/$SERIES`` branch in each library from the same + commit that was tagged, to provide a place to back-port changes for + the stable branch. + + The release team for each project will be responsible for this + step, so we will want to automate it as much as possible. + +The rest of the requirements management for the release is largely +unchanged, with one final step added: + +#. Freeze the master branch of the global requirements repository at + the Feature Freeze date. + +#. All projects merge the latest global requirements before issuing + their RC1. + +#. When projects tag their RC1 they create ``proposed/$SERIES`` + branches. + +#. When all integrated projects have done their RC1, we create a + requirements ``proposed/$SERIES`` branch and unfreeze master + +#. After all applications have released their RC1 and have created + their ``proposed/$SERIES`` branches, the caps on the global + requirements list can be removed on the master branch. + +.. _Compatible Releases: https://www.python.org/dev/peps/pep-0440/#compatible-release + +New stable releases of the library can then proceed as before, tagging +new patch releases in the stable branch instead of master. Stable +releases of libraries are expected to be exceptions, to support +security or serious bug fixes. Trivial bug fixes will not necessarily +be back-ported. As with applications stable releases of libraries +should not include new features and should have a high level of +backwards-compatibility. + +The global requirements updates for our own libraries should be merged +into the applications requirements list before their RC1 is produced +to ensure that we don't have any releases with conflicting +requirements. + +The next release on master for each library should use a new minimum +version number to move it out of the stable release series. We will +have cut the stable branch at that point, so bug fixes will have to be +a back-ported anyway. Historically feature patches that didn't make it +before the freeze have merged early in the next cycle. Taking both of +those factors together means it will just be simpler to always cut a +release with a new minor version to avoid any issues with later +back-ports or with accidentally including features in the release +going to the new stable branch. + +Management of the stable branches is left up to the projects to +decide, but it should not be assumed that the stable maintenance team +will directly handle all back-ports. + +Alternatives +------------ + +Use a "proposed" Branch before the Stable Branch +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We could follow the two-step process the applications use and create a +``proposed/$SERIES`` branch before the final ``stable`` +branch. However, the library code bases are smaller and tend to have +fewer changes in flight at any one time than the applications, so this +would be extra overhead in the process. We haven't found many cases in +the past where we need to back-port changes from master to the stable +branches, so it shouldn't be a large amount of work to do that as +needed. + +The branches for libraries are also created *after* a release, and so +they are not a "proposed" release. + +Create Stable Branches as Needed +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As mentioned above, we waited to create stable branches for some of +the Oslo libraries until they were needed. This introduced extra time +into the process because a back-port patch couldn't be submitted for +review until the branch existed. + +Create Numbered Branches +~~~~~~~~~~~~~~~~~~~~~~~~ + +We could also create branches like ``stable/1.2`` or using some other +prefix. However, this makes it more difficult to set up the test jobs +using regexes against the branch names, and especially the job that +tests proposed changes to stable branches of libraries will be more +difficult to configure properly. Using the release name as the branch +name lets all of this work "automatically" using our existing tools. + +Implementation +============== + +Assignee(s) +----------- + +Primary assignee: + Doug Hellmann + +Work Items +---------- + +1. Review and update the scripts in ``openstack-infra/release-tools`` + to find any that need to be updated to support libraries. + +.. I'll need to talk to Thierry about which scripts might need to be + updated and if there are any other written instructions that we + need to update, but I wanted to get the first draft of this spec + out for review. + + +Dependencies +============ + +None + +History +======= + +.. list-table:: Revisions + :header-rows: 1 + + * - Release Name + - Description + * - Kilo + - Introduced + +.. note:: + + This work is licensed under a Creative Commons Attribution 3.0 Unported License. + http://creativecommons.org/licenses/by/3.0/legalcode