Documentation/internals/release-process.rst

   1 ..
   2       Licensed under the Apache License, Version 2.0 (the "License"); you may
   3       not use this file except in compliance with the License. You may obtain
   4       a copy of the License at
   5
   6           http://www.apache.org/licenses/LICENSE-2.0
   7
   8       Unless required by applicable law or agreed to in writing, software
   9       distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  10       WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  11       License for the specific language governing permissions and limitations
  12       under the License.
  13
  14       Convention for heading levels in Open vSwitch documentation:
  15
  16       =======  Heading 0 (reserved for the title in a document)
  17       -------  Heading 1
  18       ~~~~~~~  Heading 2
  19       +++++++  Heading 3
  20       '''''''  Heading 4
  21
  22       Avoid deeper levels because they do not render well.
  23
  24 ============================
  25 Open vSwitch Release Process
  26 ============================
  27
  28 This document describes the process ordinarily used for Open vSwitch
  29 development and release.  Exceptions are sometimes necessary, so all of the
  30 statements here should be taken as subject to change through rough consensus of
  31 Open vSwitch contributors, obtained through public discussion on, e.g., ovs-dev
  32 or the #openvswitch IRC channel.
  33
  34 Release Strategy
  35 ----------------
  36
  37 Open vSwitch feature development takes place on the "master" branch.
  38 Ordinarily, new features are rebased against master and applied directly.  For
  39 features that take significant development, sometimes it is more appropriate to
  40 merge a separate branch into master; please discuss this on ovs-dev in advance.
  41
  42 The process of making a release has the following stages.  See `Release
  43 Scheduling`_ for the timing of each stage:
  44
  45 1. "Soft freeze" of the master branch.
  46
  47    During the freeze, we ask committers to refrain from applying patches that
  48    add new features unless those patches were already being publicly discussed
  49    and reviewed before the freeze began.  Bug fixes are welcome at any time.
  50    Please propose and discuss exceptions on ovs-dev.
  51
  52 2. Fork a release branch from master, named for the expected release number,
  53    e.g. "branch-2.3" for the branch that will yield Open vSwitch 2.3.x.
  54
  55    Release branches are intended for testing and stabilization.  At this stage
  56    and in later stages, they should receive only bug fixes, not new features.
  57    Bug fixes applied to release branches should be backports of corresponding
  58    bug fixes to the master branch, except for bugs present only on release
  59    branches (which are rare in practice).
  60
  61    At this stage, sometimes there can be exceptions to the rule that a release
  62    branch receives only bug fixes.  Like bug fixes, new features on release
  63    branches should be backports of the corresponding commits on the master
  64    branch.  Features to be added to release branches should be limited in scope
  65    and risk and discussed on ovs-dev before creating the branch.
  66
  67 3. When committers come to rough consensus that the release is ready, they
  68    release the .0 release on its branch, e.g. 2.3.0 for branch-2.3.  To make
  69    the actual release, a committer pushes a signed tag named, e.g. v2.3.0, to
  70    the Open vSwitch repository, makes a release tarball available on
  71    openvswitch.org, and posts a release announcement to ovs-announce.
  72
  73 4. As bug fixes accumulate, or after important bugs or vulnerabilities are
  74    fixed, committers may make additional releases from a branch: 2.3.1, 2.3.2,
  75    and so on.  The process is the same for these additional release as for a .0
  76    release.
  77
  78 At most three release branches are formally maintained at any given time: the
  79 latest release, the latest release designed as LTS and a previous LTS release
  80 during the transition period.  An LTS release is one that the OVS project has
  81 designated as being maintained for a longer period of time.
  82 Currently, an LTS release is maintained until the next major release after the
  83 new LTS is chosen.  This one release time frame is a transition period which is
  84 intended for users to upgrade from old LTS to new one.
  85 There is not currently a strict guideline on how often a new LTS release is
  86 chosen, but so far it has been about every 2 years.  That could change based on
  87 the current state of OVS development.  For example, we do not want to designate
  88 a new release as LTS that includes disruptive internal changes, as that may
  89 make it harder to support for a longer period of time.  Discussion about
  90 choosing the next LTS release occurs on the OVS development mailing list.
  91
  92 Release Numbering
  93 -----------------
  94
  95 The version number on master should normally end in .90.  This indicates that
  96 the Open vSwitch version is "almost" the next version to branch.
  97
  98 Forking master into branch-x.y requires two commits to master.  The first is
  99 titled "Prepare for x.y.0" and increments the version number to x.y.  This is
 100 the initial commit on branch-x.y.  The second is titled "Prepare for post-x.y.0
 101 (x.y.90)" and increments the version number to x.y.90.
 102
 103 The version number on a release branch is x.y.z, where z is initially 0.
 104 Making a release requires two commits.  The first is titled *Set release dates
 105 for x.y.z.* and updates NEWS and debian/changelog to specify the release date
 106 of the new release.  This commit is the one made into a tarball and tagged.
 107 The second is titled *Prepare for x.y.(z+1).* and increments the version number
 108 and adds a blank item to NEWS with an unspecified date.
 109
 110 Release Scheduling
 111 ------------------
 112
 113 Open vSwitch makes releases at the following six-month cadence.  All dates are
 114 approximate:
 115
 116 +---------------+----------------+--------------------------------------+
 117 | Time (months) | Dates          | Stage                                |
 118 +---------------+----------------+--------------------------------------+
 119 | T             | Mar 1, Sep 1   | Begin x.y release cycle              |
 120 +---------------+----------------+--------------------------------------+
 121 | T + 4         | Jul 1, Jan 1   | "Soft freeze" master for x.y release |
 122 +---------------+----------------+--------------------------------------+
 123 | T + 4.5       | Jul 15, Jan 15 | Fork branch-x.y from master          |
 124 +---------------+----------------+--------------------------------------+
 125 | T + 5.5       | Aug 15, Feb 15 | Release version x.y.0                |
 126 +---------------+----------------+--------------------------------------+
 127
 128 How to Branch
 129 -------------
 130
 131 To branch "master" for the eventual release of OVS version x.y.0,
 132 prepare two patches against master:
 133
 134 1. "Prepare for x.y.0." following the model of commit 836d1973c56e
 135    ("Prepare for 2.11.0.").
 136
 137 2. "Prepare for post-x.y.0 (x.y.90)." following the model of commit
 138    fe2870c574db ("Prepare for post-2.11.0 (2.11.90).")
 139
 140 Post both patches to ovs-dev.  Get them reviewed in the usual way.
 141
 142 Apply both patches to master, and create branch-x.y by pushing only
 143 the first patch.  The following command illustrates how to do both of
 144 these at once assuming the local repository HEAD points to the
 145 "Prepare for post-x.y.0" commit:
 146
 147         git push origin HEAD:master HEAD^:refs/heads/branch-x.y
 148
 149 Branching should be announced on ovs-dev.
 150
 151 How to Release
 152 --------------
 153
 154 Follow these steps to release version x.y.z of OVS from branch-x.y.
 155
 156 1. Prepare two patches against branch-x.y:
 157
 158    a. "Set release date for x.y.z".  For z = 0, follow the model of
 159       commit d11f4cbbfe05 ("Set release date for 2.12.0."); for z > 0,
 160       follow the model of commit 53d5c18118b0 ("Set release date for
 161       2.11.3.").
 162
 163    b. "Prepare for x.y.(z+1)." following the model of commit
 164       db02dd23e48a ("Prepare for 2.11.1.").
 165
 166 3. Post the patches to ovs-dev.  Get them reviewed in the usual way.
 167
 168 4. Apply the patches to branch-x.y.
 169
 170 5. If z = 0, apply the first patch (only) to master.
 171
 172 6. Sign a tag vx.y.z "Open vSwitch version x.y.z" and push it to the
 173    repo.
 174
 175 7. Update http://www.openvswitch.org/download/.  See commit
 176    31eaa72cafac ("Add 2.12.0 and older release announcements.") in the
 177    website repo (https://github.com/openvswitch/openvswitch.github.io)
 178    for an example.
 179
 180 8. Consider updating the Wikipedia page for Open vSwitch at
 181    https://en.wikipedia.org/wiki/Open_vSwitch
 182
 183 9. Tweet.
 184
 185 Contact
 186 -------
 187
 188 Use dev@openvswitch.org to discuss the Open vSwitch development and release
 189 process.