======================================== 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