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 #. Build Docker images
 149
 150    1. Log into the Netdef Docker build VM
 151    2. ``sudo -su builduser``
 152    3. Suppose we are releasing 8.5.0, then ``X.Y.Z`` is ``8.5.0``. Run this:
 153
 154       .. code-block:: console
 155
 156          cd /home/builduser/frr
 157          TAG=X.Y.Z
 158          git fetch --all
 159          git checkout frr-<version>
 160          docker buildx build --platform linux/amd64,linux/arm64,linux/ppc64le,linux/s390x,linux/arm/v7,linux/arm/v6 -f docker/alpine/Dockerfile -t quay.io/frrouting/frr:$TAG --push .
 161          git tag docker/$TAG
 162          git push origin docker/$TAG
 163
 164       This will build a multi-arch image and upload it to Quay, as well as
 165       create a git tag corresponding to the commit that the image was built
 166       from and upload that to Github. It's important that the git tag point to
 167       the exact codebase that was used to build the docker image, so if any
 168       changes need to be made on top of the ``frr-<version>`` release tag, make
 169       sure these changes are committed and pointed at by the ``docker/X.Y.Z``
 170       tag.
 171
 172
 173 Stage 3 - Publish
 174 -----------------
 175
 176 #. Upload both the Debian and RPM packages to their respective repositories.
 177
 178 #. Coordinate with the maintainer of FRR's RPM repository to publish the RPM
 179    packages on that repository. Update the repository webpage. Verify that the
 180    instructions on the webpage work and that FRR is installable from the
 181    repository on a Red Hat system.
 182
 183    Current maintainer: *Martin Winter*
 184
 185 #. Coordinate with the maintainer of FRR Debian package to publish the Debian
 186    packages on that repository. Update the repository webpage. Verify that the
 187    instructions on the webpage work and that FRR is installable from the
 188    repository on a Debian system.
 189
 190    Current maintainer: *Jafar Al-Gharaibeh*
 191
 192 #. Log in to the Read The Docs instance. in the "FRRouting" project, navigate
 193    to the "Overview" tab. Ensure there is a ``stable-<version>`` version listed
 194    and that it is enabled. Go to "Admin" and then "Advanced Settings". Change
 195    "Default version" to the new version. This ensures that the documentation
 196    shown to visitors is that of the latest release by default.
 197
 198    This step must be performed by someone with administrative access to the
 199    Read the Docs instance.
 200
 201 #. On GitHub, go to the <https://github.com/FRRouting/frr/releases>_ and click
 202    "Draft a new release". Write a release announcement. The release
 203    announcement should follow the template in
 204    ``release-announcement-template.md``, located next to this document. Check
 205    for spelling errors, and optionally (but preferably) have other maintainers
 206    proofread the announcement text.
 207
 208    Do not attach any packages or source tarballs to the GitHub release.
 209
 210    Publish the release once it is reviewed.
 211
 212 #. Deploy Snapcraft release. Remember that this will automatically upgrade Snap
 213    users.
 214
 215    Current maintainer: *Martin Winter*
 216
 217 #. Build and publish the Docker containers.
 218
 219    Current maintainer: *Quentin Young*
 220
 221 #. Clone the ``frr-www`` repository:
 222
 223    .. code-block:: console
 224
 225       git clone https://github.com/FRRouting/frr-www.git
 226
 227 #. Add a new release announcement, using a previous announcement as template:
 228
 229    .. code-block:: console
 230
 231       cp content/release/<old-version>.md content/release/<new-version>.md
 232
 233    Paste the GitHub release announcement text into this document, and **remove
 234    line breaks**. In other words, this::
 235
 236       This is one continuous
 237       sentence that should be
 238       rendered on one line
 239
 240    Needs to be changed to this::
 241
 242       This is one continuous sentence that should be rendered on one line
 243
 244    This is very important otherwise the announcement will be unreadable on the
 245    website.
 246
 247    To get the number of commiters and commits, here is a couple of handy commands:
 248
 249    .. code-block:: console
 250
 251       # The number of commits
 252       % git log --oneline --no-merges base_8.2...base_8.1 | wc -l
 253
 254       # The number of commiters
 255       % git shortlog --summary --no-merges base_8.2...base_8.1 | wc -l
 256
 257    Make sure to add a link to the GitHub releases page at the top.
 258
 259 #. Deploy the updated ``frr-www`` on the frrouting.org web server and verify
 260    that the announcement text is visible.
 261
 262 #. Update readthedocs.org (Default Version) for https://docs.frrouting.org to
 263    be the version of this latest release.
 264
 265 #. Send an email to ``announce@lists.frrouting.org``. The text of this email
 266    should include text as appropriate from the GitHub release and a link to the
 267    GitHub release, Debian repository, and RPM repository.