1 .. _frr-release-procedure:
6 ``<version>`` - version to be released, e.g. 7.3
7 ``origin`` - FRR upstream repository
12 #. Prepare changelog for the new release
14 Note: use ``tools/release_notes.py`` to help draft release notes changelog
16 #. Checkout the existing ``dev/<version>`` branch.
18 .. code-block:: console
20 git checkout dev/<version>
22 #. Create and push a new branch called ``stable/<version>`` based on the
23 ``dev/<version>`` branch.
25 .. code-block:: console
27 git checkout -b stable/<version>
29 #. Remove the development branch called ``dev/<version>``
31 .. code-block:: console
33 git push origin --delete dev/<version>
35 #. Update Changelog for Red Hat Packages:
37 Edit :file:`redhat/frr.spec.in` and look for the ``%changelog`` section:
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
44 * Tue Nov 7 2017 Martin Winter <mwinter@opensourcerouting.org> - %{version}
48 * Tue Nov 7 2017 Martin Winter <mwinter@opensourcerouting.org> - 7.2
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.
54 - Add the changelog text below this entry.
56 #. Update Changelog for Debian Packages:
58 Update :file:`debian/changelog`:
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``.
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**.
67 - Verify the changelog format using ``dpkg-parsechangelog``. In the
70 .. code-block:: console
74 You should see output like this::
76 vagrant@local ~/frr> dpkg-parsechangelog
79 Distribution: UNRELEASED
81 Maintainer: FRRouting-Dev <dev@lists.frrouting.org>
83 Date: Thu, 25 Oct 2018 16:36:50 +0200
85 frr (7.3-dev-0) RELEASED; urgency=medium
89 #. Commit the changes, adding the changelog to the commit message. Follow all
90 existing commit guidelines. The commit message should be akin to::
92 debian, redhat: updating changelog for new release
94 #. Change main version number:
96 - Edit :file:`configure.ac` and change version in the ``AC_INIT`` command
99 Add and commit this change. This commit should be separate from the commit
100 containing the changelog. The commit message should be::
102 FRR Release <version>
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``.
111 #. Push the stable branch to a new remote branch prefixed with ``rc``::
113 git push origin stable/<version>:rc/version
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:
119 https://ci1.netdef.org/browse/FRR-FRR
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.
125 #. Push the stable branch:
127 .. code-block:: console
129 git push origin stable/<version>:refs/heads/stable/<version>
131 #. Create and push a git tag for the version:
133 .. code-block:: console
135 git tag -a frr-<version> -m "FRRouting Release <version>"
136 git push origin frr-<version>
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.
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
146 #. Kick off the Snapcraft build plan for the release.
148 #. Build Docker images
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:
154 .. code-block:: console
156 cd /home/builduser/frr
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 .
162 git push origin docker/$TAG
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``
176 #. Upload both the Debian and RPM packages to their respective repositories.
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.
183 Current maintainer: *Martin Winter*
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.
190 Current maintainer: *Jafar Al-Gharaibeh*
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.
198 This step must be performed by someone with administrative access to the
199 Read the Docs instance.
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.
208 Do not attach any packages or source tarballs to the GitHub release.
210 Publish the release once it is reviewed.
212 #. Deploy Snapcraft release. Remember that this will automatically upgrade Snap
215 Current maintainer: *Martin Winter*
217 #. Build and publish the Docker containers.
219 Current maintainer: *Quentin Young*
221 #. Clone the ``frr-www`` repository:
223 .. code-block:: console
225 git clone https://github.com/FRRouting/frr-www.git
227 #. Add a new release announcement, using a previous announcement as template:
229 .. code-block:: console
231 cp content/release/<old-version>.md content/release/<new-version>.md
233 Paste the GitHub release announcement text into this document, and **remove
234 line breaks**. In other words, this::
236 This is one continuous
237 sentence that should be
240 Needs to be changed to this::
242 This is one continuous sentence that should be rendered on one line
244 This is very important otherwise the announcement will be unreadable on the
247 To get the number of commiters and commits, here is a couple of handy commands:
249 .. code-block:: console
251 # The number of commits
252 % git log --oneline --no-merges base_8.2...base_8.1 | wc -l
254 # The number of commiters
255 % git shortlog --summary --no-merges base_8.2...base_8.1 | wc -l
257 Make sure to add a link to the GitHub releases page at the top.
259 #. Deploy the updated ``frr-www`` on the frrouting.org web server and verify
260 that the announcement text is visible.
262 #. Update readthedocs.org (Default Version) for https://docs.frrouting.org to
263 be the version of this latest release.
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.