<p>Patrick Georgi has uploaded this change for <strong>review</strong>.</p><p><a href="https://review.coreboot.org/c/coreboot/+/30082">View Change</a></p><pre style="font-family: monospace,monospace; white-space: pre-wrap;">Documentation: Add documentation about the release process<br><br>It's originally written by Martin who graciously allowed to me rework it<br>a bit and push it into coreboot's documentation.<br><br>Change-Id: I14938d678e4620abec7ed5f0d35dddaf00edda6d<br>Signed-off-by: Patrick Georgi <pgeorgi@google.com><br>---<br>A Documentation/releases/checklist.md<br>M Documentation/releases/index.md<br>2 files changed, 216 insertions(+), 0 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;">git pull ssh://review.coreboot.org:29418/coreboot refs/changes/82/30082/1</pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/Documentation/releases/checklist.md b/Documentation/releases/checklist.md</span><br><span>new file mode 100644</span><br><span>index 0000000..f03f87d</span><br><span>--- /dev/null</span><br><span>+++ b/Documentation/releases/checklist.md</span><br><span>@@ -0,0 +1,210 @@</span><br><span style="color: hsl(120, 100%, 40%);">+# coreboot Release Process</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This document describes our release process and all prerequisites to implement</span><br><span style="color: hsl(120, 100%, 40%);">+it successfully.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Purpose of coreboot releases</span><br><span style="color: hsl(120, 100%, 40%);">+Our releases aren't primarily a vehicle for code that is stable across all</span><br><span style="color: hsl(120, 100%, 40%);">+boards: The logistics of testing the more than 100 boards that are spread out</span><br><span style="color: hsl(120, 100%, 40%);">+all continents (except Antarctica, probably) on a given tree state are</span><br><span style="color: hsl(120, 100%, 40%);">+prohibitive for project of our size.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Instead, the releases are regular breakpoints that serve multiple purposes:</span><br><span style="color: hsl(120, 100%, 40%);">+They support cooperation between multiple groups (corporations or otherwise)</span><br><span style="color: hsl(120, 100%, 40%);">+in that it's easier to keep source trees synchronized based on a limited set</span><br><span style="color: hsl(120, 100%, 40%);">+of commits. They allow a quick assessment of the age of any given build or</span><br><span style="color: hsl(120, 100%, 40%);">+source tree based on its git version (4.8-1234 was merged into master a few</span><br><span style="color: hsl(120, 100%, 40%);">+months after 4.8, which came out in April 2018. 4.0-21718's age is harder to</span><br><span style="color: hsl(120, 100%, 40%);">+guess).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+And finally we use releases to as points in time where we remove old code:</span><br><span style="color: hsl(120, 100%, 40%);">+Once we decide that a certain part of coreboot gets in the way of future</span><br><span style="color: hsl(120, 100%, 40%);">+development, we announce on the next release that we intend to remove that</span><br><span style="color: hsl(120, 100%, 40%);">+part - and everything that depends on it - after the following release.</span><br><span style="color: hsl(120, 100%, 40%);">+So removing feature FOO will be announced in release X for release</span><br><span style="color: hsl(120, 100%, 40%);">+X+1. The first commit after X+1 is fair game for such removal.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Together with our 6 months release horizon, this provides time to plan</span><br><span style="color: hsl(120, 100%, 40%);">+any migrations necessary to keep older boards in the tree by bringing</span><br><span style="color: hsl(120, 100%, 40%);">+them up to current standards.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Needed credentials & authorizations</span><br><span style="color: hsl(120, 100%, 40%);">+* Website access is required to post the release files to the website.</span><br><span style="color: hsl(120, 100%, 40%);">+* IRC admin access is required to update the topic.</span><br><span style="color: hsl(120, 100%, 40%);">+* Git access rights are needed to post the tag.</span><br><span style="color: hsl(120, 100%, 40%);">+* Blog post access is needed to do the blog post.</span><br><span style="color: hsl(120, 100%, 40%);">+* A PGP key is required to sign the release tarballs and git tag.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This set of required credentials implies that releases can only be done</span><br><span style="color: hsl(120, 100%, 40%);">+by a coreboot admin.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## When to release</span><br><span style="color: hsl(120, 100%, 40%);">+Releases are done roughly on a 6-month schedule, ideally around end</span><br><span style="color: hsl(120, 100%, 40%);">+of April and end of October (can be a bit earlier or delay into May</span><br><span style="color: hsl(120, 100%, 40%);">+or November).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+We initially followed a 3 month release schedule, but we found that to</span><br><span style="color: hsl(120, 100%, 40%);">+be more frequent than was needed, so we scaled it back to twice a year.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Checklist</span><br><span style="color: hsl(120, 100%, 40%);">+### ~2 weeks prior to release</span><br><span style="color: hsl(120, 100%, 40%);">+- [ ] Announce upcoming release to mailing list, ask people to test and</span><br><span style="color: hsl(120, 100%, 40%);">+ to update release notes</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### ~1 week prior to release</span><br><span style="color: hsl(120, 100%, 40%);">+- [ ] Send reminder email to mailing list, ask for people to test,</span><br><span style="color: hsl(120, 100%, 40%);">+ and to update the release notes</span><br><span style="color: hsl(120, 100%, 40%);">+- [ ] Update the topic in the irc channel with the date of the upcoming</span><br><span style="color: hsl(120, 100%, 40%);">+ release</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Day of release</span><br><span style="color: hsl(120, 100%, 40%);">+- [ ] Update release notes, without specifying release commit ids</span><br><span style="color: hsl(120, 100%, 40%);">+- [ ] Select a commit ID to base the release upon, announce to IRC,</span><br><span style="color: hsl(120, 100%, 40%);">+ ask for testing.</span><br><span style="color: hsl(120, 100%, 40%);">+- [ ] Test the commit selected for release</span><br><span style="color: hsl(120, 100%, 40%);">+- [ ] Run release script</span><br><span style="color: hsl(120, 100%, 40%);">+- [ ] Test the release from the actual release tarballs</span><br><span style="color: hsl(120, 100%, 40%);">+- [ ] Push signed Tag to repo</span><br><span style="color: hsl(120, 100%, 40%);">+- [ ] Announce that the release tag is done on IRC</span><br><span style="color: hsl(120, 100%, 40%);">+- [ ] Update release notes with actual commit id, push to repo</span><br><span style="color: hsl(120, 100%, 40%);">+- [ ] Upload release files to web server</span><br><span style="color: hsl(120, 100%, 40%);">+- [ ] Update download page to point to files, push to repo</span><br><span style="color: hsl(120, 100%, 40%);">+- [ ] Write and publish blog post with release notes.</span><br><span style="color: hsl(120, 100%, 40%);">+- [ ] Update the topic in the irc channel that the release is done.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Pre-Release tasks</span><br><span style="color: hsl(120, 100%, 40%);">+Announce the upcoming release to the mailing list release 2 weeks ahead</span><br><span style="color: hsl(120, 100%, 40%);">+of the planned release date.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The announcement should state the planned release date, point to the</span><br><span style="color: hsl(120, 100%, 40%);">+release notes that are in the making and ask people to test the hardware</span><br><span style="color: hsl(120, 100%, 40%);">+they have to make sure it's working with the current master branch,</span><br><span style="color: hsl(120, 100%, 40%);">+from which the release will ultimately be derived from.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+People should also be encouraged to provide additions to the</span><br><span style="color: hsl(120, 100%, 40%);">+release notes, for example by putting them on some [collaborative</span><br><span style="color: hsl(120, 100%, 40%);">+editor](https://www.piratenpad.de).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The final release notes will reside in coreboot's Documentation/releases</span><br><span style="color: hsl(120, 100%, 40%);">+directory, so asking for additions to that through the regular Gerrit</span><br><span style="color: hsl(120, 100%, 40%);">+process works as well. Note that git requires lots of conflict resolution</span><br><span style="color: hsl(120, 100%, 40%);">+on heavily edited text files though.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Frequently, we will want to wait until particular things are in the</span><br><span style="color: hsl(120, 100%, 40%);">+release. Once those are in, you can select the commit ID that you want</span><br><span style="color: hsl(120, 100%, 40%);">+to use for your release. For the 4.6 release, we waited until we had</span><br><span style="color: hsl(120, 100%, 40%);">+time to do the release, then pulled in a few patches that we wanted</span><br><span style="color: hsl(120, 100%, 40%);">+to have in the release. The release was based on the final of those</span><br><span style="color: hsl(120, 100%, 40%);">+patches to be pulled in.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+When a release candidate has been selected, announce the commit ID to</span><br><span style="color: hsl(120, 100%, 40%);">+the #coreboot irc channel, and request that it get some testing, just</span><br><span style="color: hsl(120, 100%, 40%);">+to make sure that everything is sane.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Generate the release</span><br><span style="color: hsl(120, 100%, 40%);">+After the commit for the release has been selected and verified, run the</span><br><span style="color: hsl(120, 100%, 40%);">+release script - util/release/build-release. This will download a new</span><br><span style="color: hsl(120, 100%, 40%);">+tree, checkout the commit that you specified, download the submodules,</span><br><span style="color: hsl(120, 100%, 40%);">+create a tag, then generate and sign the tarballs.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Be prepared to type in your PGP key’s passphrase.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+````</span><br><span style="color: hsl(120, 100%, 40%);">+usage: util/release/build-release <version> [commit id] [username] [gpg key id]</span><br><span style="color: hsl(120, 100%, 40%);">+Tags a new coreboot version and creates a tar archive</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+version: New version name to tag the tree with</span><br><span style="color: hsl(120, 100%, 40%);">+commit id: check out this commit-id after cloning the coreboot tree</span><br><span style="color: hsl(120, 100%, 40%);">+username: clone the tree using ssh://USERNAME - defaults to https://</span><br><span style="color: hsl(120, 100%, 40%);">+gpg key id: used to tag the version, and generate a gpg signature</span><br><span style="color: hsl(120, 100%, 40%);">+````</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+After running the script, you should have a new directory for the release,</span><br><span style="color: hsl(120, 100%, 40%);">+along with 4 files - 2 tarballs, and 2 signature files.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+````</span><br><span style="color: hsl(120, 100%, 40%);">+drwxr-xr-x 9 martin martin 4096 Apr 30 19:57 coreboot-4.6</span><br><span style="color: hsl(120, 100%, 40%);">+-rw-r--r-- 1 martin martin 29156788 Apr 30 19:58 coreboot-4.6.tar.xz</span><br><span style="color: hsl(120, 100%, 40%);">+-rw-r--r-- 1 martin martin 836 Apr 30 19:58 coreboot-4.6.tar.xz.sig</span><br><span style="color: hsl(120, 100%, 40%);">+-rw-r--r-- 1 martin martin 5902076 Apr 30 19:58 coreboot-blobs-4.6.tar.xz</span><br><span style="color: hsl(120, 100%, 40%);">+-rw-r--r-- 1 martin martin 836 Apr 30 19:58 coreboot-blobs-4.6.tar.xz.sig</span><br><span style="color: hsl(120, 100%, 40%);">+````</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Here’s the command that was used to generate the 4.6 release:</span><br><span style="color: hsl(120, 100%, 40%);">+````</span><br><span style="color: hsl(120, 100%, 40%);">+% util/release/build-release 4.6 db508565 Gaumless 3E4F7DF7</span><br><span style="color: hsl(120, 100%, 40%);">+````</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Test the release from the tarballs</span><br><span style="color: hsl(120, 100%, 40%);">+* Run “make what-jenkins-does” and verify that everything is building.</span><br><span style="color: hsl(120, 100%, 40%);">+* Build and test qemu</span><br><span style="color: hsl(120, 100%, 40%);">+ ````</span><br><span style="color: hsl(120, 100%, 40%);">+ cp configs/config.emulation_qemu_x86_i440fx .config; make olddefconfig; make</span><br><span style="color: hsl(120, 100%, 40%);">+ qemu-system-x86_64 -bios build/coreboot.rom -serial stdio</span><br><span style="color: hsl(120, 100%, 40%);">+ ````</span><br><span style="color: hsl(120, 100%, 40%);">+* Build and test any other platforms you can.</span><br><span style="color: hsl(120, 100%, 40%);">+* Compare the directory from the tarballs to the coreboot repo to make sure nothing went wrong.</span><br><span style="color: hsl(120, 100%, 40%);">+* Push the tag to git</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+A good tag will look like this:</span><br><span style="color: hsl(120, 100%, 40%);">+````</span><br><span style="color: hsl(120, 100%, 40%);">+% git show 4.6</span><br><span style="color: hsl(120, 100%, 40%);">+tag 4.6</span><br><span style="color: hsl(120, 100%, 40%);">+Tagger: Martin Roth <martinroth@google.com></span><br><span style="color: hsl(120, 100%, 40%);">+Date: Sun Apr 30 19:48:38 2017 -0600</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+coreboot version 4.6</span><br><span style="color: hsl(120, 100%, 40%);">+-----BEGIN PGP SIGNATURE-----</span><br><span style="color: hsl(120, 100%, 40%);">+Version: GnuPG v1</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+iQIcBAABCQAGBQJZBpP2AAoJEBl5bCs+T333xfgQAKhilfDTzqlr3MLJC4VChbmr</span><br><span style="color: hsl(120, 100%, 40%);">+...</span><br><span style="color: hsl(120, 100%, 40%);">+678e0NzyWsyqU1Vx2rdFdLANx6hghH1R7E5ybzHHUQrhb55BoEsnQMU1oS0npnT4</span><br><span style="color: hsl(120, 100%, 40%);">+dwfLho1afk0ZLPUU1JFW</span><br><span style="color: hsl(120, 100%, 40%);">+=25y8</span><br><span style="color: hsl(120, 100%, 40%);">+-----END PGP SIGNATURE-----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+commit db508565d2483394b709654c57533e55eebace51 (HEAD, tag: 4.6, origin/master, origin/HEAD)</span><br><span style="color: hsl(120, 100%, 40%);">+...</span><br><span style="color: hsl(120, 100%, 40%);">+````</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+When you used the script to generate the release, a tag was generated in the tree that was downloaded.</span><br><span style="color: hsl(120, 100%, 40%);">+From the coreboot-X.Y tree, just run: `git push -f origin <TAG (X.Y)>`</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+You will need write access for tags to the coreboot git repo to do this.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## After the release is tagged in git</span><br><span style="color: hsl(120, 100%, 40%);">+Announce that the release has been tagged - this lets people know that</span><br><span style="color: hsl(120, 100%, 40%);">+they should update their trees to grab the new tag. Until they do this,</span><br><span style="color: hsl(120, 100%, 40%);">+the version number in build.h will still be based on the previous tag.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Copy the tarballs and .sig files generated by the script to</span><br><span style="color: hsl(120, 100%, 40%);">+the coreboot server, and put them in the release directory at</span><br><span style="color: hsl(120, 100%, 40%);">+`/srv/docker/www.coreboot.org-staticfiles/releases/`</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+````</span><br><span style="color: hsl(120, 100%, 40%);">+% sha256sum -b coreboot-*.tar.xz > sha256suma.txt # Update the sha256sum file</span><br><span style="color: hsl(120, 100%, 40%);">+% diff sha256sum.txt sha256suma.txt # make sure that the two new files are present (and that nothing else has changed)</span><br><span style="color: hsl(120, 100%, 40%);">+% mv sha256suma.txt sha256sum.txt</span><br><span style="color: hsl(120, 100%, 40%);">+````</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+People can now see the release tarballs on the website at</span><br><span style="color: hsl(120, 100%, 40%);">+https://www.coreboot.org/releases/</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The downloads page is the official place to download the releases from, and it needs to be updated with links to the new release tarballs and .sig files. It can be found at https://review.coreboot.org/cgit/homepage.git/tree/downloads.html</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Here is an example commit to change it: https://review.coreboot.org/#/c/19515/</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## After the release is complete</span><br><span style="color: hsl(120, 100%, 40%);">+Post the release notes on https://blogs.coreboot.org</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Making a branch</span><br><span style="color: hsl(120, 100%, 40%);">+At times we will need to create a branch, generally for patch fixes.</span><br><span style="color: hsl(120, 100%, 40%);">+When making a branch, do NOT name it the same as the release tag: X.Y - this creates trouble when trying to check it out, as git can’t tell whether you want the tag or the branch.</span><br><span style="color: hsl(120, 100%, 40%);">+Instead, name it X.Y\_branch: `git checkout 4.8; git checkout -b 4.8_branch; git push origin 4.8_branch`</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+You can then cherry-pick changes and push them up to the branch:</span><br><span style="color: hsl(120, 100%, 40%);">+````</span><br><span style="color: hsl(120, 100%, 40%);">+git cherry-pick c6d134988c856d0025153fb885045d995bc8c397</span><br><span style="color: hsl(120, 100%, 40%);">+git push origin HEAD:refs/for/4.8_branch</span><br><span style="color: hsl(120, 100%, 40%);">+````</span><br><span>diff --git a/Documentation/releases/index.md b/Documentation/releases/index.md</span><br><span>index 602a63a..4571d12 100644</span><br><span>--- a/Documentation/releases/index.md</span><br><span>+++ b/Documentation/releases/index.md</span><br><span>@@ -10,6 +10,12 @@</span><br><span> * [4.7 - January 2018](coreboot-4.7-relnotes.md)</span><br><span> * [4.8 - May 2018](coreboot-4.8.1-relnotes.md)</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+The checklist contains instructions to ensure that a release covers all</span><br><span style="color: hsl(120, 100%, 40%);">+important things and provides a reliable format for tarballs, branch</span><br><span style="color: hsl(120, 100%, 40%);">+names etc.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* [checklist](checklist.md)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> Upcoming release</span><br><span> ----------------</span><br><span> </span><br><span></span><br></pre><p>To view, visit <a href="https://review.coreboot.org/c/coreboot/+/30082">change 30082</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://review.coreboot.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://review.coreboot.org/c/coreboot/+/30082"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: coreboot </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-Change-Id: I14938d678e4620abec7ed5f0d35dddaf00edda6d </div>
<div style="display:none"> Gerrit-Change-Number: 30082 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: Patrick Georgi <pgeorgi@google.com> </div>
<div style="display:none"> Gerrit-MessageType: newchange </div>