]>
Commit | Line | Data |
---|---|---|
f4bcc72f QY |
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 | ||
f34334ba QY |
9 | Stage 1 - Preparation |
10 | --------------------- | |
11 | ||
339bd66f JAG |
12 | #. Prepare changelog for the new release |
13 | ||
14 | Note: use ``tools/release_notes.py`` to help draft release notes changelog | |
15 | ||
4bdfe95e | 16 | #. Checkout the existing ``dev/<version>`` branch. |
f4bcc72f | 17 | |
972d7521 QY |
18 | .. code-block:: console |
19 | ||
f4bcc72f QY |
20 | git checkout dev/<version> |
21 | ||
4bdfe95e | 22 | #. Create and push a new branch called ``stable/<version>`` based on the |
f4bcc72f QY |
23 | ``dev/<version>`` branch. |
24 | ||
972d7521 | 25 | .. code-block:: console |
f4bcc72f QY |
26 | |
27 | git checkout -b stable/<version> | |
f4bcc72f | 28 | |
4bdfe95e | 29 | #. Remove the development branch called ``dev/<version>`` |
7188145f DS |
30 | |
31 | .. code-block:: console | |
32 | ||
33 | git push origin --delete dev/<version> | |
34 | ||
4bdfe95e | 35 | #. Update Changelog for Red Hat Packages: |
f4bcc72f QY |
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 | ||
4bdfe95e | 56 | #. Update Changelog for Debian Packages: |
f4bcc72f | 57 | |
25785834 | 58 | Update :file:`debian/changelog`: |
f4bcc72f | 59 | |
25785834 OS |
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``. | |
f4bcc72f | 63 | |
25785834 OS |
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**. | |
f4bcc72f QY |
66 | |
67 | - Verify the changelog format using ``dpkg-parsechangelog``. In the | |
68 | repository root: | |
69 | ||
972d7521 | 70 | .. code-block:: console |
f4bcc72f QY |
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 | . | |
972d7521 | 87 | * Your Changes Here |
f4bcc72f | 88 | |
4bdfe95e | 89 | #. Commit the changes, adding the changelog to the commit message. Follow all |
5b80c10d | 90 | existing commit guidelines. The commit message should be akin to:: |
f4bcc72f | 91 | |
5b80c10d | 92 | debian, redhat: updating changelog for new release |
f4bcc72f | 93 | |
4bdfe95e | 94 | #. Change main version number: |
f4bcc72f | 95 | |
5b80c10d QY |
96 | - Edit :file:`configure.ac` and change version in the ``AC_INIT`` command |
97 | to ``<version>`` | |
f4bcc72f | 98 | |
5b80c10d QY |
99 | Add and commit this change. This commit should be separate from the commit |
100 | containing the changelog. The commit message should be:: | |
f4bcc72f | 101 | |
4bdfe95e | 102 | FRR Release <version> |
5b80c10d QY |
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``. | |
f4bcc72f | 106 | |
f34334ba QY |
107 | |
108 | Stage 2 - Staging | |
109 | ----------------- | |
110 | ||
5530810f QY |
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 | |
f34334ba QY |
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> | |
5b80c10d | 130 | |
4bdfe95e | 131 | #. Create and push a git tag for the version: |
f4bcc72f | 132 | |
972d7521 | 133 | .. code-block:: console |
f4bcc72f | 134 | |
5b80c10d | 135 | git tag -a frr-<version> -m "FRRouting Release <version>" |
f4bcc72f QY |
136 | git push origin frr-<version> |
137 | ||
f34334ba QY |
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. | |
4bdfe95e QY |
143 | Contact Martin Winter for this step. Ensure all release packages build |
144 | successfully. | |
f4bcc72f | 145 | |
4bdfe95e | 146 | #. Kick off the Snapcraft build plan for the release. |
f4bcc72f | 147 | |
5c6b543b QY |
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 | ||
f4bcc72f | 172 | |
f34334ba QY |
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. | |
f4bcc72f | 182 | |
f34334ba | 183 | Current maintainer: *Martin Winter* |
f4bcc72f | 184 | |
f34334ba QY |
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. | |
f4bcc72f | 189 | |
f34334ba | 190 | Current maintainer: *Jafar Al-Gharaibeh* |
f4bcc72f | 191 | |
b7ca0bc3 QY |
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. | |
f4bcc72f | 200 | |
f34334ba QY |
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* | |
f4bcc72f | 220 | |
4bdfe95e | 221 | #. Clone the ``frr-www`` repository: |
f4bcc72f | 222 | |
4bdfe95e | 223 | .. code-block:: console |
f4bcc72f | 224 | |
4bdfe95e | 225 | git clone https://github.com/FRRouting/frr-www.git |
f4bcc72f | 226 | |
4bdfe95e | 227 | #. Add a new release announcement, using a previous announcement as template: |
f4bcc72f | 228 | |
4bdfe95e | 229 | .. code-block:: console |
f4bcc72f | 230 | |
5c1d2850 | 231 | cp content/release/<old-version>.md content/release/<new-version>.md |
f4bcc72f | 232 | |
4bdfe95e QY |
233 | Paste the GitHub release announcement text into this document, and **remove |
234 | line breaks**. In other words, this:: | |
972d7521 | 235 | |
4bdfe95e QY |
236 | This is one continuous |
237 | sentence that should be | |
238 | rendered on one line | |
972d7521 | 239 | |
4bdfe95e | 240 | Needs to be changed to this:: |
972d7521 | 241 | |
4bdfe95e | 242 | This is one continuous sentence that should be rendered on one line |
972d7521 | 243 | |
4bdfe95e QY |
244 | This is very important otherwise the announcement will be unreadable on the |
245 | website. | |
f4bcc72f | 246 | |
5c1d2850 DA |
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 | ||
4bdfe95e | 257 | Make sure to add a link to the GitHub releases page at the top. |
f4bcc72f | 258 | |
4bdfe95e QY |
259 | #. Deploy the updated ``frr-www`` on the frrouting.org web server and verify |
260 | that the announcement text is visible. | |
f4bcc72f | 261 | |
59a5f546 DA |
262 | #. Update readthedocs.org (Default Version) for https://docs.frrouting.org to |
263 | be the version of this latest release. | |
264 | ||
4bdfe95e | 265 | #. Send an email to ``announce@lists.frrouting.org``. The text of this email |
f34334ba QY |
266 | should include text as appropriate from the GitHub release and a link to the |
267 | GitHub release, Debian repository, and RPM repository. |