blob: f71a41105acd95702d70a772dcb27814117ce9ad [file] [log] [blame] [view]
Mike Frysingera26c49e2018-12-12 03:34:28 -05001# repo release process
2
3This is the process for creating a new release of repo, as well as all the
4related topics and flows.
5
6[TOC]
7
Mike Frysinger89f3ae52020-07-08 15:02:39 -04008## Schedule
9
10There is no specific schedule for when releases are made.
11Usually it's more along the lines of "enough minor changes have been merged",
12or "there's a known issue the maintainers know should get fixed".
13If you find a fix has been merged for an issue important to you, but hasn't been
14released after a week or so, feel free to [contact] us to request a new release.
15
16### Release Freezes {#freeze}
17
18We try to observe a regular schedule for when **not** to release.
19If something goes wrong, staff need to be active in order to respond quickly &
20effectively.
21We also don't want to disrupt non-Google organizations if possible.
22
23We generally follow the rules:
24
25* Release during Mon - Thu, 9:00 - 14:00 [US PT]
26* Avoid holidays
27 * All regular [US holidays]
28 * Large international ones if possible
29 * All the various [New Years]
30 * Jan 1 in Gregorian calendar is the most obvious
31 * Check for large Lunar New Years too
32* Follow the normal [Google production freeze schedule]
33
34[US holidays]: https://en.wikipedia.org/wiki/Federal_holidays_in_the_United_States
35[US PT]: https://en.wikipedia.org/wiki/Pacific_Time_Zone
36[New Years]: https://en.wikipedia.org/wiki/New_Year
37[Google production freeze schedule]: http://goto.google.com/prod-freeze
38
Mike Frysingera26c49e2018-12-12 03:34:28 -050039## Launcher script
40
41The main repo script serves as a standalone program and is often referred to as
42the "launcher script".
43This makes it easy to copy around and install as you don't have to install any
44other files from the git repo.
45
46Whenever major changes are made to the launcher script, you should increment the
47`VERSION` variable in the launcher itself.
48At runtime, repo will check this to see if it needs to be updated (and notify
49the user automatically).
50
51## Key management
52
53Every release has a git tag that is signed with a key that repo recognizes.
54Those keys are hardcoded inside of the repo launcher itself -- look for the
55`KEYRING_VERSION` and `MAINTAINER_KEYS` settings.
56
57Adding new keys to the repo launcher will allow tags to be recognized by new
58keys, but only people using that updated version will be able to.
59Since the majority of users will be using an official launcher version, their
60version will simply ignore any new signed tags.
61
62If you want to add new keys, it's best to register them long ahead of time,
63and then wait for that updated launcher to make its way out to everyone.
64Even then, there will be a long tail of users with outdated launchers, so be
65prepared for people asking questions.
66
67### Registering a new key
68
69The process of actually adding a new key is quite simple.
70
711. Add the public half of the key to `MAINTAINER_KEYS`.
722. Increment `KEYRING_VERSION` so repo knows it needs to update.
733. Wait a long time after that version is in a release (~months) before trying
74 to create a new release using those new keys.
75
76## Self update algorithm
77
78When creating a new repo checkout with `repo init`, there are a few options that
79control how repo finds updates:
80
81* `--repo-url`: This tells repo where to clone the full repo project itself.
82 It defaults to the official project (`REPO_URL` in the launcher script).
Mike Frysinger58ac1672020-03-14 14:35:26 -040083* `--repo-rev`: This tells repo which branch to use for the full project.
Mike Frysingera26c49e2018-12-12 03:34:28 -050084 It defaults to the `stable` branch (`REPO_REV` in the launcher script).
85
Mike Frysinger2ee0a622021-05-04 15:16:38 -040086Whenever `repo sync` is run, repo will, once every 24 hours, see if an update
87is available.
Mike Frysinger58ac1672020-03-14 14:35:26 -040088It fetches the latest repo-rev from the repo-url.
Mike Frysingera26c49e2018-12-12 03:34:28 -050089Then it verifies that the latest commit in the branch has a valid signed tag
90using `git tag -v` (which uses gpg).
91If the tag is valid, then repo will update its internal checkout to it.
92
93If the latest commit doesn't have a signed tag, repo will fall back to the
94most recent tag it can find (via `git describe`).
95If that tag is valid, then repo will warn and use that commit instead.
96
97If that tag cannot be verified, it gives up and forces the user to resolve.
98
Mike Frysinger2ee0a622021-05-04 15:16:38 -040099### Force an update
100
101The `repo selfupdate` command can be used to force an immediate update.
102It is not subject to the 24 hour limitation.
103
Mike Frysingera26c49e2018-12-12 03:34:28 -0500104## Branch management
105
Mike Frysinger6e89c962020-11-15 18:42:26 -0500106All development happens on the `main` branch and should generally be stable.
Mike Frysingera26c49e2018-12-12 03:34:28 -0500107
108Since the repo launcher defaults to tracking the `stable` branch, it is not
109normally updated until a new release is available.
110If something goes wrong with a new release, an older release can be force pushed
111and clients will automatically downgrade.
112
113The `maint` branch is used to track the previous major release of repo.
114It is not normally meant to be used by people as `stable` should be good enough.
115Once a new major release is pushed to the `stable` branch, then the previous
116major release can be pushed to `maint`.
117For example, when `stable` moves from `v1.10.x` to `v1.11.x`, then the `maint`
118branch will be updated from `v1.9.x` to `v1.10.x`.
119
120We don't have parallel release branches/series.
Mike Frysinger6e89c962020-11-15 18:42:26 -0500121Typically all tags are made against the `main` branch and then pushed to the
Mike Frysingera26c49e2018-12-12 03:34:28 -0500122`stable` branch to make it available to the rest of the world.
123Since repo doesn't typically see a lot of changes, this tends to be OK.
124
125## Creating a new release
126
127When you want to create a new release, you'll need to select a good version and
128create a signed tag using a key registered in repo itself.
Mike Frysinger6e89c962020-11-15 18:42:26 -0500129Typically we just tag the latest version of the `main` branch.
Mike Frysingera26c49e2018-12-12 03:34:28 -0500130The tag could be pushed now, but it won't be used by clients normally (since the
Mike Frysinger58ac1672020-03-14 14:35:26 -0400131default `repo-rev` setting is `stable`).
Mike Frysinger6e89c962020-11-15 18:42:26 -0500132This would allow some early testing on systems who explicitly select `main`.
Mike Frysingera26c49e2018-12-12 03:34:28 -0500133
134### Creating a signed tag
135
136Lets assume your keys live in a dedicated directory, e.g. `~/.gnupg/repo/`.
137
138*** note
139If you need access to the official keys, check out the internal documentation
140at [go/repo-release].
141Note that only official maintainers of repo will have access as it describes
142internal processes for accessing the restricted keys.
143***
144
145```sh
146# Set the gpg key directory.
147$ export GNUPGHOME=~/.gnupg/repo/
148
149# Verify the listed key is “Repo Maintainer”.
150$ gpg -K
151
152# Pick whatever branch or commit you want to tag.
Mike Frysinger6e89c962020-11-15 18:42:26 -0500153$ r=main
Mike Frysingera26c49e2018-12-12 03:34:28 -0500154
155# Pick the new version.
156$ t=1.12.10
157
158# Create the signed tag.
159$ git tag -s v$t -u "Repo Maintainer <[email protected]>" -m "repo $t" $r
160
161# Verify the signed tag.
162$ git show v$t
163```
164
165### Push the new release
166
167Once you're ready to make the release available to everyone, push it to the
168`stable` branch.
169
170Make sure you never push the tag itself to the stable branch!
171Only push the commit -- notice the use of `$t` and `$r` below.
172
173```sh
174$ git push https://gerrit-review.googlesource.com/git-repo v$t
175$ git push https://gerrit-review.googlesource.com/git-repo $r:stable
176```
177
178If something goes horribly wrong, you can force push the previous version to the
179`stable` branch and people should automatically recover.
180Again, make sure you never push the tag itself!
181
182```sh
183$ oldrev="whatever-old-commit"
184$ git push https://gerrit-review.googlesource.com/git-repo $oldrev:stable --force
185```
186
187### Announce the release
188
189Once you do push a new release to `stable`, make sure to announce it on the
190[[email protected]] group.
191Here is an [example announcement].
192
193You can create a short changelog using the command:
194
195```sh
196# If you haven't pushed to the stable branch yet, you can use origin/stable.
197# If you have pushed, change origin/stable to the previous release tag.
198$ git log --format="%h (%aN) %s" --no-merges origin/stable..$r
199```
200
Mike Frysinger3645bd22020-02-11 18:43:34 -0500201## Project References
Mike Frysingera26c49e2018-12-12 03:34:28 -0500202
Mike Frysinger3645bd22020-02-11 18:43:34 -0500203Here's a table showing the relationship of major tools, their EOL dates, and
204their status in Ubuntu & Debian.
205Those distros tend to be good indicators of how long we need to support things.
206
207Things in bold indicate stuff to take note of, but does not guarantee that we
208still support them.
209Things in italics are things we used to care about but probably don't anymore.
210
Mike Frysingerd669d2d2021-09-24 01:32:07 -0400211| Date | EOL | [Git][rel-g] | [Python][rel-p] | [SSH][rel-o] | [Ubuntu][rel-u] / [Debian][rel-d] | Git | Python | SSH |
212|:--------:|:------------:|:------------:|:---------------:|:------------:|-----------------------------------|-----|--------|-----|
213| Apr 2008 | | | | 5.0 |
214| Jun 2008 | | | | 5.1 |
215| Oct 2008 | *Oct 2013* | | 2.6.0 | | *10.04 Lucid* - 10.10 Maverick / *Squeeze* |
Mike Frysinger3645bd22020-02-11 18:43:34 -0500216| Dec 2008 | *Feb 2009* | | 3.0.0 |
Mike Frysingerd669d2d2021-09-24 01:32:07 -0400217| Feb 2009 | | | | 5.2 |
218| Feb 2009 | *Mar 2012* | | | | Debian 5 Lenny | 1.5.6.5 | 2.5.2 |
219| Jun 2009 | *Jun 2016* | | 3.1.0 | | *10.04 Lucid* - 10.10 Maverick / *Squeeze* |
220| Sep 2009 | | | | 5.3 | *10.04 Lucid* |
221| Feb 2010 | *Oct 2012* | 1.7.0 | | | *10.04 Lucid* - *12.04 Precise* - 12.10 Quantal |
222| Mar 2010 | | | | 5.4 |
223| Apr 2010 | | | | 5.5 | 10.10 Maverick |
224| Apr 2010 | *Apr 2015* | | | | *10.04 Lucid* | 1.7.0.4 | 2.6.5 3.1.2 | 5.3 |
225| Jul 2010 | *Dec 2019* | | *2.7.0* | | 11.04 Natty - *<current>* |
226| Aug 2010 | | | | 5.6 |
227| Oct 2010 | | | | | 10.10 Maverick | 1.7.1 | 2.6.6 3.1.3 | 5.5 |
228| Jan 2011 | | | | 5.7 |
229| Feb 2011 | | | | 5.8 | 11.04 Natty |
230| Feb 2011 | *Feb 2016* | | | | Debian 6 Squeeze | 1.7.2.5 | 2.6.6 3.1.3 |
231| Apr 2011 | | | | | 11.04 Natty | 1.7.4 | 2.7.1 3.2.0 | 5.8 |
232| Sep 2011 | | | | 5.9 | *12.04 Precise* |
233| Oct 2011 | *Feb 2016* | | 3.2.0 | | 11.04 Natty - 12.10 Quantal |
234| Oct 2011 | | | | | 11.10 Ocelot | 1.7.5.4 | 2.7.2 3.2.2 | 5.8 |
235| Apr 2012 | | | | 6.0 | 12.10 Quantal |
236| Apr 2012 | *Apr 2019* | | | | *12.04 Precise* | 1.7.9.5 | 2.7.3 3.2.3 | 5.9 |
237| Aug 2012 | | | | 6.1 | 13.04 Raring |
238| Sep 2012 | *Sep 2017* | | 3.3.0 | | 13.04 Raring - 13.10 Saucy |
239| Oct 2012 | *Dec 2014* | 1.8.0 | | | 13.04 Raring - 13.10 Saucy |
240| Oct 2012 | | | | | 12.10 Quantal | 1.7.10.4 | 2.7.3 3.2.3 | 6.0 |
241| Mar 2013 | | | | 6.2 | 13.10 Saucy |
242| Apr 2013 | | | | | 13.04 Raring | 1.8.1.2 | 2.7.4 3.3.1 | 6.1 |
243| May 2013 | *May 2018* | | | | Debian 7 Wheezy | 1.7.10.4 | 2.7.3 3.2.3 |
244| Sep 2013 | | | | 6.3 |
245| Oct 2013 | | | | | 13.10 Saucy | 1.8.3.2 | 2.7.5 3.3.2 | 6.2 |
246| Nov 2013 | | | | 6.4 |
247| Jan 2014 | | | | 6.5 |
248| Feb 2014 | *Dec 2014* | **1.9.0** | | | *14.04 Trusty* |
249| Mar 2014 | *Mar 2019* | | *3.4.0* | | *14.04 Trusty* - 15.10 Wily / *Jessie* |
250| Mar 2014 | | | | 6.6 | *14.04 Trusty* - 14.10 Utopic |
251| Apr 2014 | *Apr 2022* | | | | *14.04 Trusty* | 1.9.1 | 2.7.5 3.4.0 | 6.6 |
Mike Frysinger3645bd22020-02-11 18:43:34 -0500252| May 2014 | *Dec 2014* | 2.0.0 |
Mike Frysingerd669d2d2021-09-24 01:32:07 -0400253| Aug 2014 | *Dec 2014* | *2.1.0* | | | 14.10 Utopic - 15.04 Vivid / *Jessie* |
254| Oct 2014 | | | | 6.7 | 15.04 Vivid |
255| Oct 2014 | | | | | 14.10 Utopic | 2.1.0 | 2.7.8 3.4.2 | 6.6 |
Mike Frysinger3645bd22020-02-11 18:43:34 -0500256| Nov 2014 | *Sep 2015* | 2.2.0 |
257| Feb 2015 | *Sep 2015* | 2.3.0 |
Mike Frysingerd669d2d2021-09-24 01:32:07 -0400258| Mar 2015 | | | | 6.8 |
Mike Frysinger3645bd22020-02-11 18:43:34 -0500259| Apr 2015 | *May 2017* | 2.4.0 |
Mike Frysingerd669d2d2021-09-24 01:32:07 -0400260| Apr 2015 | *Jun 2020* | | | | *Debian 8 Jessie* | 2.1.4 | 2.7.9 3.4.2 |
261| Apr 2015 | | | | | 15.04 Vivid | 2.1.4 | 2.7.9 3.4.3 | 6.7 |
262| Jul 2015 | *May 2017* | 2.5.0 | | | 15.10 Wily |
263| Jul 2015 | | | | 6.9 | 15.10 Wily |
264| Aug 2015 | | | | 7.0 |
265| Aug 2015 | | | | 7.1 |
Mike Frysinger3645bd22020-02-11 18:43:34 -0500266| Sep 2015 | *May 2017* | 2.6.0 |
Mike Frysingerd669d2d2021-09-24 01:32:07 -0400267| Sep 2015 | *Sep 2020* | | *3.5.0* | | *16.04 Xenial* - 17.04 Zesty / *Stretch* |
268| Oct 2015 | | | | | 15.10 Wily | 2.5.0 | 2.7.9 3.4.3 | 6.9 |
269| Jan 2016 | *Jul 2017* | *2.7.0* | | | *16.04 Xenial* |
270| Feb 2016 | | | | 7.2 | *16.04 Xenial* |
Mike Frysinger3645bd22020-02-11 18:43:34 -0500271| Mar 2016 | *Jul 2017* | 2.8.0 |
Mike Frysingerd669d2d2021-09-24 01:32:07 -0400272| Apr 2016 | *Apr 2024* | | | | *16.04 Xenial* | 2.7.4 | 2.7.11 3.5.1 | 7.2 |
273| Jun 2016 | *Jul 2017* | 2.9.0 | | | 16.10 Yakkety |
274| Jul 2016 | | | | 7.3 | 16.10 Yakkety |
Mike Frysinger3645bd22020-02-11 18:43:34 -0500275| Sep 2016 | *Sep 2017* | 2.10.0 |
Mike Frysingerd669d2d2021-09-24 01:32:07 -0400276| Oct 2016 | | | | | 16.10 Yakkety | 2.9.3 | 2.7.11 3.5.1 | 7.3 |
277| Nov 2016 | *Sep 2017* | *2.11.0* | | | 17.04 Zesty / *Stretch* |
278| Dec 2016 | **Dec 2021** | | **3.6.0** | | 17.10 Artful - **18.04 Bionic** - 18.10 Cosmic |
279| Dec 2016 | | | | 7.4 | 17.04 Zesty / *Debian 9 Stretch* |
Mike Frysinger3645bd22020-02-11 18:43:34 -0500280| Feb 2017 | *Sep 2017* | 2.12.0 |
Mike Frysingerd669d2d2021-09-24 01:32:07 -0400281| Mar 2017 | | | | 7.5 | 17.10 Artful |
282| Apr 2017 | | | | | 17.04 Zesty | 2.11.0 | 2.7.13 3.5.3 | 7.4 |
Mike Frysinger3645bd22020-02-11 18:43:34 -0500283| May 2017 | *May 2018* | 2.13.0 |
Mike Frysingerd669d2d2021-09-24 01:32:07 -0400284| Jun 2017 | *Jun 2022* | | | | *Debian 9 Stretch* | 2.11.0 | 2.7.13 3.5.3 | 7.4 |
285| Aug 2017 | *Dec 2019* | 2.14.0 | | | 17.10 Artful |
Mike Frysinger3645bd22020-02-11 18:43:34 -0500286| Oct 2017 | *Dec 2019* | 2.15.0 |
Mike Frysingerd669d2d2021-09-24 01:32:07 -0400287| Oct 2017 | | | | 7.6 | **18.04 Bionic** |
288| Oct 2017 | | | | | 17.10 Artful | 2.14.1 | 2.7.14 3.6.3 | 7.5 |
Mike Frysinger3645bd22020-02-11 18:43:34 -0500289| Jan 2018 | *Dec 2019* | 2.16.0 |
Mike Frysingerd669d2d2021-09-24 01:32:07 -0400290| Apr 2018 | *Mar 2021* | **2.17.0** | | | **18.04 Bionic** |
291| Apr 2018 | | | | 7.7 | 18.10 Cosmic |
292| Apr 2018 | **Apr 2028** | | | | **18.04 Bionic** | 2.17.0 | 2.7.15 3.6.5 | 7.6 |
293| Jun 2018 | *Mar 2021* | 2.18.0 |
294| Jun 2018 | **Jun 2023** | | 3.7.0 | | 19.04 Disco - **20.04 Focal** / **Buster** |
295| Aug 2018 | | | | 7.8 |
296| Sep 2018 | *Mar 2021* | 2.19.0 | | | 18.10 Cosmic |
297| Oct 2018 | | | | 7.9 | 19.04 Disco / **Buster** |
298| Oct 2018 | | | | | 18.10 Cosmic | 2.19.1 | 2.7.15 3.6.6 | 7.7 |
299| Dec 2018 | *Mar 2021* | **2.20.0** | | | 19.04 Disco - 19.10 Eoan / **Buster** |
300| Feb 2019 | *Mar 2021* | 2.21.0 |
301| Apr 2019 | | | | 8.0 | 19.10 Eoan |
302| Apr 2019 | | | | | 19.04 Disco | 2.20.1 | 2.7.16 3.7.3 | 7.9 |
Mike Frysinger3645bd22020-02-11 18:43:34 -0500303| Jun 2019 | | 2.22.0 |
Mike Frysingerd669d2d2021-09-24 01:32:07 -0400304| Jul 2019 | **Jul 2024** | | | | **Debian 10 Buster** | 2.20.1 | 2.7.16 3.7.3 | 7.9 |
305| Aug 2019 | *Mar 2021* | 2.23.0 |
306| Oct 2019 | **Oct 2024** | | 3.8.0 | | **20.04 Focal** - 20.10 Groovy |
307| Oct 2019 | | | | 8.1 |
308| Oct 2019 | | | | | 19.10 Eoan | 2.20.1 | 2.7.17 3.7.5 | 8.0 |
309| Nov 2019 | *Mar 2021* | 2.24.0 |
310| Jan 2020 | *Mar 2021* | 2.25.0 | | | **20.04 Focal** |
311| Feb 2020 | | | | 8.2 | **20.04 Focal** |
312| Mar 2020 | *Mar 2021* | 2.26.0 |
313| Apr 2020 | **Apr 2030** | | | | **20.04 Focal** | 2.25.1 | 2.7.17 3.8.2 | 8.2 |
314| May 2020 | *Mar 2021* | 2.27.0 | | | 20.10 Groovy |
315| May 2020 | | | | 8.3 |
316| Jul 2020 | *Mar 2021* | 2.28.0 |
317| Sep 2020 | | | | 8.4 | 21.04 Hirsute / **Bullseye** |
318| Oct 2020 | *Mar 2021* | 2.29.0 |
319| Oct 2020 | | | | | 20.10 Groovy | 2.27.0 | 2.7.18 3.8.6 | 8.3 |
320| Oct 2020 | **Oct 2025** | | 3.9.0 | | 21.04 Hirsute / **Bullseye** |
321| Dec 2020 | *Mar 2021* | 2.30.0 | | | 21.04 Hirsute / **Bullseye** |
322| Mar 2021 | | 2.31.0 |
323| Mar 2021 | | | | 8.5 |
324| Apr 2021 | | | | 8.6 |
325| Apr 2021 | *Jan 2022* | | | | 21.04 Hirsute | 2.30.2 | 2.7.18 3.9.4 | 8.4 |
326| Jun 2021 | | 2.32.0 |
327| Aug 2021 | | 2.33.0 |
328| Aug 2021 | | | | 8.7 |
329| Aug 2021 | **Aug 2026** | | | | **Debian 11 Bullseye** | 2.30.2 | 2.7.18 3.9.2 | 8.4 |
330| **Date** | **EOL** | **[Git][rel-g]** | **[Python][rel-p]** | **[SSH][rel-o]** | **[Ubuntu][rel-u] / [Debian][rel-d]** | **Git** | **Python** | **SSH** |
Mike Frysinger3645bd22020-02-11 18:43:34 -0500331
332
Mike Frysinger89f3ae52020-07-08 15:02:39 -0400333[contact]: ../README.md#contact
Mike Frysinger3645bd22020-02-11 18:43:34 -0500334[rel-d]: https://en.wikipedia.org/wiki/Debian_version_history
335[rel-g]: https://en.wikipedia.org/wiki/Git#Releases
Mike Frysingerd669d2d2021-09-24 01:32:07 -0400336[rel-o]: https://www.openssh.com/releasenotes.html
Mike Frysinger3645bd22020-02-11 18:43:34 -0500337[rel-p]: https://en.wikipedia.org/wiki/History_of_Python#Table_of_versions
338[rel-u]: https://en.wikipedia.org/wiki/Ubuntu_version_history#Table_of_versions
Mike Frysingera26c49e2018-12-12 03:34:28 -0500339[example announcement]: https://groups.google.com/d/topic/repo-discuss/UGBNismWo1M/discussion
340[[email protected]]: https://groups.google.com/forum/#!forum/repo-discuss
341[go/repo-release]: https://goto.google.com/repo-release