doc/developer/frr-release-procedure.rst

   1 .. _frr-release-procedure:
   2
   3 FRR Release Procedure
   4 =====================
   5
   6 ``<version>`` - version to be released, e.g. 7.3
   7 ``origin`` - FRR upstream repository
   8
   9 Stage 1 - Preparation
  10 ---------------------
  11
  12 #. Prepare changelog for the new release
  13
  14    Note: use ``tools/release_notes.py`` to help draft release notes changelog
  15
  16 #. Checkout the existing ``dev/<version>`` branch.
  17
  18    .. code-block:: console
  19
  20       git checkout dev/<version>
  21
  22 #. Create and push a new branch called ``stable/<version>`` based on the
  23    ``dev/<version>`` branch.
  24
  25    .. code-block:: console
  26
  27       git checkout -b stable/<version>
  28
  29 #. Remove the development branch called ``dev/<version>``
  30
  31    .. code-block:: console
  32
  33       git push origin --delete dev/<version>
  34
  35 #. Update Changelog for Red Hat Packages:
  36
  37    Edit :file:`redhat/frr.spec.in` and look for the ``%changelog`` section:
  38
  39    - Change last (top of list) entry from ``%{version}`` to the **last**
  40      released version number. For example, if ``<version>`` is ``7.3`` and the
  41      last public release was ``7.2``, you would use ``7.2``, changing the file
  42      like so::
  43
  44         * Tue Nov  7 2017 Martin Winter <mwinter@opensourcerouting.org> - %{version}
  45
  46      to::
  47
  48         * Tue Nov  7 2017 Martin Winter <mwinter@opensourcerouting.org> - 7.2
  49
  50    - Add new entry to the top of the list with ``%{version}`` tag.  Make sure
  51      to watch the format, i.e. the day is always 2 characters, with the 1st
  52      character being a space if the day is one digit.
  53
  54    - Add the changelog text below this entry.
  55
  56 #. Update Changelog for Debian Packages:
  57
  58    Update :file:`debian/changelog`:
  59
  60    - Run following with **last** release version number and debian revision
  61      (usually -1) as argument to ``dch --newversion VERSION``. For example, if
  62      ``<version>`` is ``7.3`` then you will run ``dch --newversion 7.3-1``.
  63
  64    - The ``dch`` will run an editor, and you should add the changelog text below
  65      this entry, usually that would be: **New upstream version**.
  66
  67    - Verify the changelog format using ``dpkg-parsechangelog``. In the
  68      repository root:
  69
  70      .. code-block:: console
  71
  72         dpkg-parsechangelog
  73
  74      You should see output like this::
  75
  76         vagrant@local ~/frr> dpkg-parsechangelog
  77         Source: frr
  78         Version: 7.3-dev-0
  79         Distribution: UNRELEASED
  80         Urgency: medium
  81         Maintainer: FRRouting-Dev <dev@lists.frrouting.org>
  82         Timestamp: 1540478210
  83         Date: Thu, 25 Oct 2018 16:36:50 +0200
  84         Changes:
  85          frr (7.3-dev-0) RELEASED; urgency=medium
  86          .
  87            * Your Changes Here
  88
  89 #. Commit the changes, adding the changelog to the commit message. Follow all
  90    existing commit guidelines. The commit message should be akin to::
  91
  92       debian, redhat: updating changelog for new release
  93
  94 #. Change main version number:
  95
  96    - Edit :file:`configure.ac` and change version in the ``AC_INIT`` command
  97      to ``<version>``
  98
  99    Add and commit this change. This commit should be separate from the commit
 100    containing the changelog. The commit message should be::
 101
 102       FRR Release <version>
 103
 104    The version field should be complete; i.e. for ``8.0.0``, the version should
 105    be ``8.0.0`` and not ``8.0`` or ``8``.
 106
 107
 108 Stage 2 - Staging
 109 -----------------
 110
 111 #. Push the stable branch to a new remote branch prefixed with ``rc``::
 112
 113       git push origin stable/<version>:rc/version
 114
 115    This will trigger the NetDEF CI, which serve as a sanity check on the
 116    release branch. Verify that all tests pass and that all package builds are
 117    successful. To do this, go to the NetDEF CI located here:
 118
 119    https://ci1.netdef.org/browse/FRR-FRR
 120
 121    In the top left, look for ``rc-<version>`` in the "Plan branch" dropdown.
 122    Select this version. Note that it may take a few minutes for the CI to kick
 123    in on this new branch and appear in the list.
 124
 125 #. Push the stable branch:
 126
 127    .. code-block:: console
 128
 129       git push origin stable/<version>:refs/heads/stable/<version>
 130
 131 #. Create and push a git tag for the version:
 132
 133    .. code-block:: console
 134
 135       git tag -a frr-<version> -m "FRRouting Release <version>"
 136       git push origin frr-<version>
 137
 138 #. Create a new branch based on ``master``, cherry-pick the commit made earlier
 139    that added the changelogs, and use it to create a PR against ``master``.
 140    This way ``master`` has the latest changelog for the next cycle.
 141
 142 #. Kick off the "Release" build plan on the CI system for the correct release.
 143    Contact Martin Winter for this step. Ensure all release packages build
 144    successfully.
 145
 146 #. Kick off the Snapcraft build plan for the release.
 147
 148
 149 Stage 3 - Publish
 150 -----------------
 151
 152 #. Upload both the Debian and RPM packages to their respective repositories.
 153
 154 #. Coordinate with the maintainer of FRR's RPM repository to publish the RPM
 155    packages on that repository. Update the repository webpage. Verify that the
 156    instructions on the webpage work and that FRR is installable from the
 157    repository on a Red Hat system.
 158
 159    Current maintainer: *Martin Winter*
 160
 161 #. Coordinate with the maintainer of FRR Debian package to publish the Debian
 162    packages on that repository. Update the repository webpage. Verify that the
 163    instructions on the webpage work and that FRR is installable from the
 164    repository on a Debian system.
 165
 166    Current maintainer: *Jafar Al-Gharaibeh*
 167
 168 #. Log in to the Read The Docs instance. in the "FRRouting" project, navigate
 169    to the "Overview" tab. Ensure there is a ``stable-<version>`` version listed
 170    and that it is enabled. Go to "Admin" and then "Advanced Settings". Change
 171    "Default version" to the new version. This ensures that the documentation
 172    shown to visitors is that of the latest release by default.
 173
 174    This step must be performed by someone with administrative access to the
 175    Read the Docs instance.
 176
 177 #. On GitHub, go to the <https://github.com/FRRouting/frr/releases>_ and click
 178    "Draft a new release". Write a release announcement. The release
 179    announcement should follow the template in
 180    ``release-announcement-template.md``, located next to this document. Check
 181    for spelling errors, and optionally (but preferably) have other maintainers
 182    proofread the announcement text.
 183
 184    Do not attach any packages or source tarballs to the GitHub release.
 185
 186    Publish the release once it is reviewed.
 187
 188 #. Deploy Snapcraft release. Remember that this will automatically upgrade Snap
 189    users.
 190
 191    Current maintainer: *Martin Winter*
 192
 193 #. Build and publish the Docker containers.
 194
 195    Current maintainer: *Quentin Young*
 196
 197 #. Clone the ``frr-www`` repository:
 198
 199    .. code-block:: console
 200
 201       git clone https://github.com/FRRouting/frr-www.git
 202
 203 #. Add a new release announcement, using a previous announcement as template:
 204
 205    .. code-block:: console
 206
 207       cp <old-version>.md <version>.md
 208
 209    Paste the GitHub release announcement text into this document, and **remove
 210    line breaks**. In other words, this::
 211
 212       This is one continuous
 213       sentence that should be
 214       rendered on one line
 215
 216    Needs to be changed to this::
 217
 218       This is one continuous sentence that should be rendered on one line
 219
 220    This is very important otherwise the announcement will be unreadable on the
 221    website.
 222
 223    Make sure to add a link to the GitHub releases page at the top.
 224
 225    Once finished, manually add a new entry into ``index.html`` to link to this
 226    new announcement. Look at past commits to see how to do this.
 227
 228 #. Deploy the updated ``frr-www`` on the frrouting.org web server and verify
 229    that the announcement text is visible.
 230
 231 #. Send an email to ``announce@lists.frrouting.org``. The text of this email
 232    should include text as appropriate from the GitHub release and a link to the
 233    GitHub release, Debian repository, and RPM repository.