5 # coreboot Release Process
7 This document describes our release process and all prerequisites to
8 implement it successfully.
11 ## Purpose of coreboot releases
12 Our releases aren't primarily a vehicle for code that is stable across
13 all boards: The logistics of testing the more than 100 boards that are
14 spread out all continents (except Antarctica, probably) on a given tree
15 state are prohibitive for project of our size.
17 Instead, the releases are regular breakpoints that serve multiple
18 purposes: They support cooperation between multiple groups (corporations
19 or otherwise) in that it's easier to keep source trees synchronized
20 based on a limited set of commits. They allow a quick assessment of the
21 age of any given build or source tree based on its git version (4.8-1234
22 was merged into master a few months after 4.8, which came out in April
23 of 2018. 4.0-21718's age is harder to guess).
25 And finally we use releases to as points in time where we remove old
26 code: Once we decide that a certain part of coreboot gets in the way of
27 future development, we announce on the next release that we intend to
28 remove that part - and everything that depends on it - after the
29 following release. So removing feature FOO will be announced in release
30 X for release X+1. The first commit after X+1 is fair game for such
33 Together with our 3 months release horizon, this provides time to plan
34 any migrations necessary to keep older boards in the tree by bringing
35 them up to current standards.
37 ## coreboot release team
38 To avoid issues of blocking the release on a single person, a release
39 team has been formed. Please see the `COREBOOT RELEASES` section of the
40 MAINTAINERS file for the current members.
42 These individuals work together to make sure releases are done on time,
43 follow the steps of this document, and update the release processes and
47 ## Needed credentials & authorizations
49 ### coreboot admins only
50 * Website access is required to post the release files to the website.
52 ### All release team members
53 * IRC topic access is required to update the topic.
54 * Git access rights are needed to post the tag.
55 * Blog post access is needed to do the blog post.
56 * A PGP key is required to sign the release tarballs and git tag.
58 Most of the steps in the release process can be done by anyone on the
59 release team. Only adding the files to the website needs to be done
60 by a coreboot administrator.
63 Releases are done roughly on a 3-month schedule. If a release is
64 delayed, the next release will still be 3 months after the last release.
69 ### ~6 weeks prior to release
70 - [ ] Announce upcoming release to mailing list, ask people to test and
71 to update release notes.
72 - [ ] Start marking patches that should to go into the release with a
73 tag "coreboot_release_X.yy".
75 ### ~4 weeks prior to release
76 - [ ] Freeze toolchain state. Only relevant fixes are allowed from this point on.
77 - [ ] Schedule release meetings.
79 ### ~2 weeks prior to release
80 - [ ] Meet with release team.
81 - [ ] Send reminder email to mailing list, ask for people to test, and to update the release notes.
82 - [ ] Update the topic in the IRC channel with the date of the upcoming release.
84 ### ~1 week prior to release
85 - [ ] Meet with release team.
86 - [ ] Send reminder email to mailing list, ask for people to test,
87 and to update the release notes.
88 - [ ] Update the topic in the IRC channel with the date of the upcoming
90 - [ ] If there are any deprecations announced for the following release,
91 make sure that a list of currently affected boards and chipsets is
92 part of the release notes.
93 - [ ] Finalize release notes as much as possible.
94 - [ ] Prepare release notes template for following release.
95 - [ ] Update `Documentation/releases/index.md.
96 - [ ] Check which branches need to be released. Any branch with changes
97 should get a new release. Announce these branch releases and
98 prepare release notes.
100 ### Day before release tag
101 - [ ] Make sure patches with tags for the release are merged.
102 - [ ] Announce to IRC that the release will be tomorrow and ask for
104 - [ ] Run `util/vboot_list/vboot_list.sh` script to update the list of
105 boards supported by vboot.
107 ### Day of release tag
108 - [ ] Meet with release team.
109 - [ ] Review the full documentation about doing the release below.
110 - [ ] Select a commit ID to base the release upon.
111 - [ ] Test the commit selected for release.
112 - [ ] Submit last pre-release release notes.
113 - [ ] Run the release script.
114 - [ ] Test the release from the actual release tarballs.
115 - [ ] Push signed Tag to repo. *This is the actual release step.*
116 Once this patch is pushed, the release itself has been done.
117 everything after this step is packaging and delivering the
120 - [ ] Announce that the release tag is done on IRC.
121 - [ ] Update the topic in the IRC channel that the release is done.
123 - [ ] Do the final release notes - Fill in the release date, remove
124 "Upcoming release" and other filler from the current release
126 - [ ] ADMIN: Upload release files to web server.
127 - [ ] ADMIN: Upload the final release notes to the web server.
128 - [ ] ADMIN: Upload crossgcc sources to web server.
129 - [ ] Create coreboot-sdk and coreboot-jenkins-node docker images
130 based on the release ID and push them to dockerhub. These
131 can be used as release builders.
133 ### Week following the release
134 - [ ] Do the final release notes - Fill in the release date, remove "Upcoming release"
135 and other filler from the current release notes.
136 - [ ] ADMIN: Upload release files & toolchain tarballs to the web server.
137 - [ ] ADMIN: Upload the final release notes to the web server.
138 - [ ] ADMIN: Upload crossgcc sources to the web server.
139 - [ ] Create coreboot-sdk and coreboot-jenkins-node docker images based on the release ID
140 and push them to dockerhub. These can be used as release builders.
141 - [ ] Update download page to point to files, push to repo.
142 - [ ] Remove code that was announced it was going to be removed.
143 - [ ] Update AUTHORS file with any new authors.
144 - [ ] Update Documentation/releases/boards_supported_on_branches.md.
146 ### 7 days after release tag
147 - [ ] Meet with release team.
148 - [ ] Write and publish blog post with release final notes. Branch releases notes (if any)
149 should be included in the same post.
150 - [ ] Set up for next release.
153 ### Creating a branch
154 - [ ] Branches are named 4.xx_branch to differentiate from the tags.
155 Instructions on creating branches are listed below.
159 Announce the upcoming release to the mailing list release 2 weeks ahead
160 of the planned release date.
162 The announcement should state the planned release date, point to the
163 release notes that are in the making and ask people to test the hardware
164 they have to make sure it's working with the current master branch,
165 from which the release will ultimately be derived from.
167 People should be encouraged to provide additions to the release notes.
169 The final release notes will reside in coreboot's Documentation/releases
170 directory, so asking for additions to that through the regular Gerrit
171 process works as well. Note that git requires lots of conflict
172 resolution on heavily edited text files though.
174 Frequently, we will want to wait until particular things are in the
175 release. Once those are in, you can select the commit ID that you want
176 to use for your release. For the 4.6 release, we waited until we had
177 time to do the release, then pulled in a few patches that we wanted
178 to have in the release. The release was based on the final of those
179 patches to be pulled in.
181 When a release candidate has been selected, announce the commit ID to
182 the #coreboot IRC channel, and request that it get some testing, just
183 to make sure that everything is sane.
186 ## Generate the release
187 After the commit for the release has been selected and verified, run the
188 release script - util/release/build-release. This will download a new
189 tree, checkout the commit that you specified, download the submodules,
190 create a tag, then generate and sign the tarballs.
192 **Be prepared to type in your PGP key’s passphrase.**
195 usage: util/release/build-release <version> [commit id] [username] [gpg key id]
196 Tags a new coreboot version and creates a tar archive
198 version: New version name to tag the tree with
199 commit id: check out this commit-id after cloning the coreboot tree
200 username: clone the tree using ssh://USERNAME - defaults to https://
201 gpg key id: used to tag the version, and generate a gpg signature
204 After running the script, you should have a new directory for the
205 release, along with 4 files: 2 tarballs, and 2 signature files.
208 drwxr-xr-x 9 martin martin 4096 Apr 30 19:57 coreboot-4.6
209 -rw-r--r-- 1 martin martin 29156788 Apr 30 19:58 coreboot-4.6.tar.xz
210 -rw-r--r-- 1 martin martin 836 Apr 30 19:58 coreboot-4.6.tar.xz.sig
211 -rw-r--r-- 1 martin martin 5902076 Apr 30 19:58 coreboot-blobs-4.6.tar.xz
212 -rw-r--r-- 1 martin martin 836 Apr 30 19:58 coreboot-blobs-4.6.tar.xz.sig
215 Here’s the command that was used to generate the 4.6 release:
217 util/release/build-release 4.6 db508565 Gaumless 3E4F7DF7
221 ## Test the release from the tarballs
222 * Run “make what-jenkins-does” and verify that everything is building.
223 * Build and test qemu
225 cp configs/config.emulation_qemu_x86_i440fx .config
228 qemu-system-x86_64 -bios build/coreboot.rom -serial stdio
230 * Build and test any other platforms you can.
231 * Compare the directory from the tarballs to the coreboot repo to make
232 sure nothing went wrong.
233 * Push the tag to git
235 A good tag will look like this:
239 Tagger: Martin Roth <martinroth@google.com>
240 Date: Sun Apr 30 19:48:38 2017 -0600
243 -----BEGIN PGP SIGNATURE-----
246 iQIcBAABCQAGBQJZBpP2AAoJEBl5bCs+T333xfgQAKhilfDTzqlr3MLJC4VChbmr
248 678e0NzyWsyqU1Vx2rdFdLANx6hghH1R7E5ybzHHUQrhb55BoEsnQMU1oS0npnT4
251 -----END PGP SIGNATURE-----
253 commit db508565d2483394b709654c57533e55eebace51 (HEAD, tag: 4.6, origin/master, origin/HEAD)
257 ## Push the signed tag
258 When you used the script to generate the release, a signed tag was
259 generated in the tree that was downloaded. From the coreboot-X.Y tree,
260 just run: `git push origin X.Y`. In case you pushed the wrong tag
261 already, you have to force push the new one.
263 You will need write access for tags to the coreboot git repo to do this.
266 ## After the release is tagged in git
267 Announce that the release has been tagged - this lets people know that
268 they should update their trees to grab the new tag. Until they do this,
269 the version number in build.h will still be based on the previous tag.
271 Copy the tarballs and .sig files generated by the script to
272 the coreboot server, and put them in the release directory at
273 `/srv/docker/www.coreboot.org-staticfiles/releases/`
276 # Update the sha256sum file
277 sha256sum -b coreboot-*.tar.xz > sha256suma.txt
279 # make sure the two new files are present (and nothing else has changed)
280 diff sha256sum.txt sha256suma.txt
282 mv sha256suma.txt sha256sum.txt
285 People can now see the release tarballs on the website at
286 <https://www.coreboot.org/releases/>
288 The downloads page is the official place to download the releases from,
289 and it needs to be updated with links to the new release tarballs and
290 .sig files. It can be found at:
291 <https://review.coreboot.org/cgit/homepage.git/tree/downloads.html>
293 Here is an example commit to change it:
294 <https://review.coreboot.org/c/homepage/+/19515>
297 ## Upload crossgcc sources
298 Sometimes the source files for older revisions of
299 crossgcc disappear. To deal with that we maintain a mirror at
300 <https://www.coreboot.org/releases/crossgcc-sources/> where we host the
301 sources used by the crossgcc scripts that are part of coreboot releases.
306 util/crossgcc/buildgcc -u
309 This will output the set of URLs that the script uses to download the
310 sources. Download them yourself and copy them into the crossgcc-sources
311 directory on the server.
314 ## After the release is complete
315 Post the final release notes on <https://blogs.coreboot.org>
319 At times we will need to create a branch, generally for patch fixes.
320 When making a branch, do NOT name it the same as the release tag: X.Y -
321 this creates trouble when trying to check it out, as git can’t tell
322 whether you want the tag or the branch. Instead, name it X.Y\_branch:
325 git checkout -b 4.8_branch
326 git push origin 4.8_branch
329 You can then cherry-pick changes and push them up to the branch:
331 git cherry-pick c6d134988c856d0025153fb885045d995bc8c397
332 git push origin HEAD:refs/for/4.8_branch