|
1
|
+- **NOTE**: All examples in this template reference the rebase from Firefox 129.0a1 to 130.0a1
|
|
2
|
+- **TODO**:
|
|
3
|
+ - Documentation step for any difficulties or noteworthy things for each rapid rebase
|
|
4
|
+
|
|
5
|
+<details>
|
|
6
|
+ <summary>Explanation of Channels</summary>
|
|
7
|
+
|
|
8
|
+ There are unfortunately some collisions between how we and Mozilla name our release channels which can make things confusing:
|
|
9
|
+ - **Firefox**:
|
|
10
|
+ - **Nightly**: \_START and \_END tags, version in the format `$(MAJOR).$(MINOR)a1`
|
|
11
|
+ - **Example**: Firefox Nightly 130 was `130.0a1`
|
|
12
|
+ - **Note**: Nightly is 2 major versions ahead of the current Release
|
|
13
|
+ - **Beta**: tagged each Monday, Wednesday, and Friday until release, version in the format `$(MAJOR).$(MINOR)b$(PATCH)`
|
|
14
|
+ - **Example**: the first Firefox Beta 130 was `130.0b1`
|
|
15
|
+ - **Note**: Beta is 1 major version ahead of the current Release, should be irrelevant to us
|
|
16
|
+ - **Release**: tagged monthly, version in the format `$(MAJOR).$(MINOR)` or `$(MAJOR).$(MINOR).$(PATCH)`
|
|
17
|
+ - **Example** Firefox Release 130 was `130.0`
|
|
18
|
+ - **ESR**: tagged monthly, version in the format `$(ESR_MAJOR).$(ESR_MINOR).$(ESR_PATCH)esr`
|
|
19
|
+ - **Example**: Firefox ESR 128.1 is `128.1.0esr`
|
|
20
|
+ - **Tor+Mullvad Browser**:
|
|
21
|
+ - **Rapid**: tagged monthly, based on the latest Firefox Nightly
|
|
22
|
+ - **Nightly**: not tagged, built nightly from our current Alpha branch's `HEAD`
|
|
23
|
+ - **Alpha**: tagged monthly, based on the latest Firefox ESR
|
|
24
|
+ - **Stable**: tagged monthly, based on oldest supported Firefox ESR
|
|
25
|
+
|
|
26
|
+</details>
|
|
27
|
+
|
|
28
|
+<details>
|
|
29
|
+ <summary>Branching Overview</summary>
|
|
30
|
+
|
|
31
|
+ Rebasing Tor Browser Rapid onto the current Firefox Nightly is a bit more confusing/involved than rebasing Tor Browser Alpha or Stable from one minor ESR to the next minor ESR.
|
|
32
|
+
|
|
33
|
+ The general process basically involves rebasing the previous Firefox Nightly-based Tor Browser Rapid onto the latest Firefox Nightly, and then cherry-picking all of the commits from the previous Firefox ESR-based Tor Browser Alpha after that channel's `build1` tag. This process presumes that the previous Tor Browser Alpha branch is locked and receiving no more changes.
|
|
34
|
+
|
|
35
|
+ This diagram provides a high-level view of the overall code-flow for rebasing/cherry-picking commits from Tor Browser Alpha based on Firefox 128.1.0esr and Tor Browser Rapid based on Firefox 129.0a1 onto Firefox 130.0a1:
|
|
36
|
+
|
|
37
|
+ ```mermaid
|
|
38
|
+%%{init: { 'themeVariables': {'git0': '#0072b2', 'gitBranchLabel0': '#fff', 'git1': "#e69f00", 'gitBranchLabel1': '#fff', 'git2': '#009e73', 'gitBranchLabel2': '#fff', 'git3': '#cc79a7', 'gitBranchLabel3': '#fff'}, 'gitGraph': {'mainBranchName': 'tor-browser-128.1.0esr-14.5-1'}} }%%
|
|
39
|
+gitGraph:
|
|
40
|
+ branch tor-browser-129.0a1-15.0-2
|
|
41
|
+ branch tor-browser-130.0a1-15.0-1
|
|
42
|
+ branch tor-browser-130.0a1-15.0-2
|
|
43
|
+
|
|
44
|
+ checkout tor-browser-128.1.0esr-14.5-1
|
|
45
|
+ commit id: "FIREFOX_128_1_0esr_BUILD1"
|
|
46
|
+ commit id: "base-browser-128.1.0esr-14.5-1-build1"
|
|
47
|
+ commit id: "tor-browser-128.1.0esr-14.5-1-build1"
|
|
48
|
+ commit id: "tor-browser-128.1.0esr-14.5-1-build2"
|
|
49
|
+
|
|
50
|
+ checkout tor-browser-129.0a1-15.0-2
|
|
51
|
+ commit id: "FIREFOX_NIGHTLY_129_END"
|
|
52
|
+ %% commit id: "tor-browser-129.0a1-15.0-2-build1"
|
|
53
|
+
|
|
54
|
+ checkout tor-browser-130.0a1-15.0-1
|
|
55
|
+ commit id: "FIREFOX_NIGHTLY_130_END"
|
|
56
|
+
|
|
57
|
+ checkout tor-browser-130.0a1-15.0-2
|
|
58
|
+ commit id: "FIREFOX_NIGHTLY_130_END "
|
|
59
|
+
|
|
60
|
+ checkout tor-browser-130.0a1-15.0-1
|
|
61
|
+ merge tor-browser-129.0a1-15.0-2
|
|
62
|
+
|
|
63
|
+ checkout tor-browser-130.0a1-15.0-2
|
|
64
|
+ merge tor-browser-130.0a1-15.0-1
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+ checkout tor-browser-129.0a1-15.0-2
|
|
68
|
+ commit id: "tor-browser-129.0a1-15.0-2-build1"
|
|
69
|
+
|
|
70
|
+ checkout tor-browser-130.0a1-15.0-1
|
|
71
|
+ merge tor-browser-129.0a1-15.0-2 id: "tor-browser-130.0a1-15.0-1-build1"
|
|
72
|
+
|
|
73
|
+ checkout tor-browser-130.0a1-15.0-2
|
|
74
|
+ merge tor-browser-130.0a1-15.0-1
|
|
75
|
+
|
|
76
|
+ checkout tor-browser-130.0a1-15.0-1
|
|
77
|
+ merge tor-browser-128.1.0esr-14.5-1
|
|
78
|
+
|
|
79
|
+ checkout tor-browser-130.0a1-15.0-2
|
|
80
|
+ merge tor-browser-130.0a1-15.0-1
|
|
81
|
+
|
|
82
|
+ checkout tor-browser-128.1.0esr-14.5-1
|
|
83
|
+ commit id: "tor-browser-128.1.0esr-14.5-1"
|
|
84
|
+
|
|
85
|
+ checkout tor-browser-130.0a1-15.0-1
|
|
86
|
+ merge tor-browser-128.1.0esr-14.5-1 id:"tor-browser-130.0a1-15.0-1-build2"
|
|
87
|
+
|
|
88
|
+ checkout tor-browser-130.0a1-15.0-2
|
|
89
|
+
|
|
90
|
+ merge tor-browser-130.0a1-15.0-1
|
|
91
|
+ commit id: "tor-browser-130.0a1-15.0-2-build1"
|
|
92
|
+
|
|
93
|
+ ```
|
|
94
|
+
|
|
95
|
+ In this concrete example, the rebaser performs the following steps:
|
|
96
|
+ - create new `tor-browser-130.0a1-15.0-1`, and `tor-browser-130.0a1-15.0-2` branches from the `FIREFOX_NIGHTLY_130_END` tag.
|
|
97
|
+ - these will be the rebase review branches
|
|
98
|
+ - onto `tor-browser-130.0a1-15.0-1`, cherry-pick the range `FIREFOX_NIGHTLY_129_END..tor-browser-129.0a1-15.0-2-build1` (i.e. the Firefox Nightly 129-based Tor Browser Rapid commits)
|
|
99
|
+ - this updates the previous Tor Browser Rapid onto Firefox Nightly 130
|
|
100
|
+ - cherry-pick the new alpha patches onto `tor-browser-130.0a1-15.0-1` (i.e. cherry-pick `tor-browser-128.1.0esr-14.5-1-build2..origin/tor-browser-128.1.0esr-14.5-1`)
|
|
101
|
+ - onto `tor-browser-130.0a1-15.0-2`, rebase and autosquash the `FIREFOX_NIGHTLY_130_END..tor-browser-130.0a1-15.0-2-build1` commit range
|
|
102
|
+ - onto `tor-browser-130.0a1-15.0-2`, cherry-pick the remaining commit range `tor-browser-130.0a1-15.0-2-build1..origin/tor-browser-130.0a1-15.0-2`
|
|
103
|
+ - re-order any remaining fixup! commits to be adjacent to their parents (i.e. the same rebase command queue as one would get from `git rebase --autosquash`, but with the `fixup!` commands replaced with `pick!` commands).
|
|
104
|
+ - this re-organises the branch in a nicely-bisectable way, and will ensure the rebase+autosquash step for the next release *should* succeed without any additional effort
|
|
105
|
+
|
|
106
|
+</details>
|
|
107
|
+
|
|
108
|
+<details>
|
|
109
|
+ <summary>Explanation of Variables</summary>
|
|
110
|
+
|
|
111
|
+- `$(NIGHTLY_VERSION)`: the Mozilla defined nightly version, used in various places for building tor-browser tags, labels, etc
|
|
112
|
+ - **Example**: `130.0a1`
|
|
113
|
+- `$(NIGHTLY_TAG)`: the Mozilla defined hg (Mercurial) tag associated with `$(NIGHTLY_VERSION)`
|
|
114
|
+ - **Example**: `FIREFOX_NIGHTLY_130_END`
|
|
115
|
+- `$(NIGHTLY_TAG_PREV)`: the Mozilla defined hg (Mercurial) tag associated with the previous nightly version when rebasing (ie, the nightly version we are rebasing from)
|
|
116
|
+ - **Example**: `FIREFOX_NIGHTLY_129_END`
|
|
117
|
+- `$(BROWSER_VERSION)`: the browser version which will first be based on the next major ESR version this *Firefox* Nightly series is leading up to
|
|
118
|
+ - **Example**: `15`
|
|
119
|
+- `$(TOR_BROWSER_BRANCH)`: the full name of the current `tor-browser` branch based off of the Firefox Nightly channel
|
|
120
|
+ - **Example**: `tor-browser-130.0a1-15.0-1`
|
|
121
|
+- `$(TOR_BROWSER_BRANCH_PREV)`: the full name of the previous `tor-browser` branch based off of the Firefox Nightly channel
|
|
122
|
+ - **Example**: `tor-browser-129.0a1-15.0-1`
|
|
123
|
+</details>
|
|
124
|
+
|
|
125
|
+### Update Branch Protection Rules
|
|
126
|
+
|
|
127
|
+- [ ] In [Repository Settings](https://gitlab.torproject.org/tpo/applications/tor-browser/-/settings/repository):
|
|
128
|
+ - [ ] Remove previous nightly `tor-browser` branch protection rules (this will prevent pushing new changes to the branches being rebased)
|
|
129
|
+ - [ ] Create new `tor-browser` branch protection rule:
|
|
130
|
+ - **Branch**: `tor-browser-$(NIGHTLY_VERSION)-$(BROWSER_VERSION)-*`
|
|
131
|
+ - **Example**: `tor-browser-130.0a1-15.0-*`
|
|
132
|
+ - **Allowed to merge**: `Maintainers`
|
|
133
|
+ - **Allowed to push and merge**: `Maintainers`
|
|
134
|
+ - **Allowed to force push**: `false`
|
|
135
|
+ - ⚠️ **IMPORTANT**: If you copied and pasted from old rules, double check you didn't add spaces at the end, as GitLab will not trim them!
|
|
136
|
+
|
|
137
|
+### **Create New Branches**
|
|
138
|
+
|
|
139
|
+- [ ] Find the Firefox mercurial tag `$(NIGHTLY_TAG)`
|
|
140
|
+ - Go to https://hg.mozilla.org/mozilla-central/tags
|
|
141
|
+ - Find and inspect the commit tagged with `$(NIGHTLY_TAG)`
|
|
142
|
+ - Tags are in yellow in the Mercurial web UI
|
|
143
|
+ - Find the equivalent commit in https://github.com/mozilla/gecko-dev/commits/master
|
|
144
|
+ - **Notice**: GitHub sorts commits by time, you might want to use `git log gecko-dev/master` locally, instead
|
|
145
|
+ - Using the differential revision link is useful to quickly find the git commit
|
|
146
|
+ - Sign/Tag the `gecko-dev` commit: `git tag -as $(NIGHTLY_TAG) $(GIT_HASH) -m "Hg tag $(NIGHTLY_TAG)"`
|
|
147
|
+- [ ] Create two new rapid `tor-browser` branches from Firefox mercurial tag
|
|
148
|
+ - Branch name in the form: `tor-browser-$(NIGHTLY_VERSION)-$(BROWSER_VERSION)-${BRANCH_NUM}`
|
|
149
|
+ - **Example**: `tor-browser-130.0a1-15.0-1` and `tor-browser-130.0a1-15.0-2`
|
|
150
|
+- [ ] Push new `tor-browser` branches and the `firefox` tag to `upstream`
|
|
151
|
+
|
|
152
|
+### **Rebase previous `-2` rapid branch's HEAD onto current `-1` rapid branch**
|
|
153
|
+
|
|
154
|
+- **Desired outcome**:
|
|
155
|
+ - An easy to review branch with the previous rapid branch rebased onto the latest Firefox Nighty tag
|
|
156
|
+ - It must be possible to run `git range-diff` between the previous `-2` and the new branch
|
|
157
|
+ - We want to see only the effects of the rebase
|
|
158
|
+ - No autosquash should happen at this point
|
|
159
|
+ - **Expected difficulties**:
|
|
160
|
+ - Conflicts with upstream developments
|
|
161
|
+ - Sometimes it will be hard to keep a feature working. It's fine to drop it, and create an issue to restore it after a deeper investigation.
|
|
162
|
+- [ ] Checkout a new local branch for the first part of the `-1` rebase
|
|
163
|
+ - **Example**: `git checkout -b rapid-rebase-part1 origin/tor-browser-130.0a1-15.0-1`
|
|
164
|
+- [ ] Firefox Nightly-based `tor-browser` rebase:
|
|
165
|
+ - [ ] cherry-pick previous Tor Browser Rapid `-2` branch to new `-1` rebase branch
|
|
166
|
+ - **Example**: `git cherry-pick FIREFOX_NIGHTLY_129_END..origin/tor-browser-129.0a1-15.0-2`
|
|
167
|
+- [ ] Rebase Verification:
|
|
168
|
+ - [ ] Clean range-diff between the previous rapid branch and current rebase branch
|
|
169
|
+ - **Example**:
|
|
170
|
+ ```bash
|
|
171
|
+ git range-diff FIREFOX_NIGHTLY_129_END..origin/tor-browser-129.0a1-15.0-2 FIREFOX_NIGHTLY_130_END..rapid-rebase-part1
|
|
172
|
+ ```
|
|
173
|
+ - [ ] Optional: clean diff of diffs between previous rapid branch and current rebase branch
|
|
174
|
+ - **Example**:
|
|
175
|
+ ```bash
|
|
176
|
+ git diff FIREFOX_NIGHTLY_129_END origin/tor-browser-129.0a1-15.0-2 > 129.diff
|
|
177
|
+ git diff FIREFOX_NIGHTLY_130_END HEAD > 130.diff
|
|
178
|
+ # A two-column diff tool is suggested rather than plain-diff, e.g., meld on Linux.
|
|
179
|
+ meld 129.diff 130.diff
|
|
180
|
+ ```
|
|
181
|
+ - **Note**: Only differences should be due to resolving merge conflicts with upstream changes from Firefox Nightly
|
|
182
|
+- [ ] Open MR
|
|
183
|
+- [ ] Merge
|
|
184
|
+- [ ] Sign/Tag `HEAD` of the merged `tor-browser` branch:
|
|
185
|
+ - In **tor-browser.git**, checkout the `-1` rapid `tor-browser` branch
|
|
186
|
+ - In **tor-browser-build.git**, run signing script:
|
|
187
|
+ ```bash
|
|
188
|
+ ./tools/browser/sign-tag.torbrowser rapid build1
|
|
189
|
+ ```
|
|
190
|
+ - [ ] Push tag to `upstream`
|
|
191
|
+
|
|
192
|
+### **Port new alpha patches to `-1`**
|
|
193
|
+
|
|
194
|
+- **Desired outcome**:
|
|
195
|
+ - The previous release-cycle's new alpha patches cherry-picked to the end of the current nightly
|
|
196
|
+ - It must be possible to run `git range-diff ESR-build1..ESR NIGHTLY-build1..`
|
|
197
|
+ - **Expected difficulties**:
|
|
198
|
+ - Conflicts with upstream developments (similar to the previous part)
|
|
199
|
+ - The range might contain cherry-picked upstream commits, which will result in empty commits: it's fine to skip them
|
|
200
|
+ - **Note**: The Tor Browser Alpha branch should be closed at this point and not receiving any more MRs
|
|
201
|
+- [ ] Checkout a new local branch for the second part of the `-1` rebase
|
|
202
|
+ - **Example**: `git checkout -b rapid-rebase-part2 origin/tor-browser-130.0a1-15.0-1`
|
|
203
|
+- [ ] Cherry-pick the new `tor-browser` alpha commits (i.e. the new dangling commits which did not appear in the previous Tor Browser Alpha release):
|
|
204
|
+ - **Example** `git cherry-pick tor-browser-128.1.0esr-14.5-1-build1..origin/tor-browser-128.1.0esr-14.5-1`
|
|
205
|
+- [ ] Rebase Verification
|
|
206
|
+ - [ ] Clean range-diff between the alpha patch set ranges
|
|
207
|
+ - **Example**:
|
|
208
|
+ ```bash
|
|
209
|
+ git range-diff tor-browser-128.1.0esr-14.5-1-build1..origin/tor-browser-128.1.0esr-14.5-1 origin/tor-browser-130.0a1-15.0-1..HEAD
|
|
210
|
+ ```
|
|
211
|
+ - [ ] Clean diff of diffs between the alpha patch set ranges
|
|
212
|
+ - **Example**:
|
|
213
|
+ ```bash
|
|
214
|
+ git diff tor-browser-128.1.0esr-14.5-1-build1 origin/tor-browser-128.1.0esr-14.5-1 > 128.1.0esr.diff
|
|
215
|
+ git diff origin/tor-browser-130.0a1-15.0-1 HEAD > 130.diff
|
|
216
|
+ # A two-column diff tool is suggested rather than plain-diff, e.g., meld on Linux.
|
|
217
|
+ meld 128.1.0esr.diff 130.diff
|
|
218
|
+ ```
|
|
219
|
+ - **Note**: Only differences should be due to resolving merge conflicts with upstream changes from Firefox Nightly
|
|
220
|
+- [ ] Open MR
|
|
221
|
+- [ ] Merge
|
|
222
|
+- [ ] Sign/Tag `HEAD` of the merged `tor-browser` branch:
|
|
223
|
+ - In **tor-browser.git**, checkout the `-1` rapid `tor-browser` branch
|
|
224
|
+ - In **tor-browser-build.git**, run signing script:
|
|
225
|
+ ```bash
|
|
226
|
+ ./tools/browser/sign-tag.torbrowser rapid build2
|
|
227
|
+ ```
|
|
228
|
+ - [ ] Push tag to `upstream`
|
|
229
|
+
|
|
230
|
+### **Squash and Reorder tor-browser `-1` branch to new `-2` branch**
|
|
231
|
+- **Desired outcome**:
|
|
232
|
+ - The rapid branch from the previous step prepared for the next nightly
|
|
233
|
+ - **Rationale**:
|
|
234
|
+ - We squash a lot of commits. We want to keep them a little bit longer rather than squashing them immediately for troubleshooting and documentation purposes.
|
|
235
|
+ - Doing this as a separate pass helps to separate errors due to upstream changes from errors due to processes created by our workflow.
|
|
236
|
+ - **Expected difficulties**:
|
|
237
|
+ - our patches aren't disjoint, therefore we might have conflicts when shuffling them around.
|
|
238
|
+- [ ] Checkout a new local branch for the `-2` rebase, aligned to -1-build1
|
|
239
|
+ - **Example**: `git checkout -b rapid-rebase-part3 tor-browser-130.0a1-15.0-1-build1`
|
|
240
|
+- [ ] Rebase with autosquash. This step should be trivial and not involve any conflicts.
|
|
241
|
+ - **Example**: `git rebase -i --autosquash FIREFOX_NIGHTLY_130_END`
|
|
242
|
+- [ ] Cherry-pick the remaining commits
|
|
243
|
+ - **Example**: `git cherry-pick tor-browser-130.0a1-15.0-1-build1..upstream/tor-browser-130.0a1-15.0-1`
|
|
244
|
+- [ ] Create a branch for self-reviewing purposes, or take note of the current commit hash somewhere
|
|
245
|
+ - **Example**: `git branch rapid-rebase-part3-review`
|
|
246
|
+ - You do not need to publish this, and you can delete it at the end of the process (`git branch -D rapid-rebase-part3-review`)
|
|
247
|
+ - When you are a reviewer, it might be useful to repeat these steps locally. They should not involve mental overhead (and PieroV has a script to automate this)
|
|
248
|
+- [ ] Rebase and reorder commits (i.e. replace `fixup `, `fixup -C ` and `squash ` with `pick ` commands)
|
|
249
|
+ - Notice the space at the end, to avoid replacing `fixup!` with `pick!` in the commit subject, even though git will probably not care of such changes
|
|
250
|
+- [ ] Rebase Verification
|
|
251
|
+ - [ ] Clean range-diff between the temporary review branch and the final branch
|
|
252
|
+ - **Example**:
|
|
253
|
+ ```bash
|
|
254
|
+ git range-diff FIREFOX_NIGHTLY_130_END..rapid-rebase-part3-review FIREFOX_NIGHTLY_130_END..rapid-rebase-part3
|
|
255
|
+ ```
|
|
256
|
+ - If you are the reviewer, it should be trivial to create such a branch on your own, as no shuffling is involved
|
|
257
|
+ - [ ] Clean diff of diffs between rapid branches
|
|
258
|
+ - **Example**:
|
|
259
|
+ ```bash
|
|
260
|
+ git diff FIREFOX_NIGHTLY_130_END tor-browser-130.0a1-15.0-1-build2 > 130-1.diff
|
|
261
|
+ git diff FIREFOX_NIGHTLY_130_END HEAD > 130-2.diff
|
|
262
|
+ ```
|
|
263
|
+ - [ ] Understandable range-diff (i.e. `fixup!` patches are distributed from end of branch next to their parent)
|
|
264
|
+ - **Example**:
|
|
265
|
+ ```bash
|
|
266
|
+ git range-diff FIREFOX_NIGHTLY_130_END..tor-browser-130.0a1-15.0-1-build2 FIREFOX_NIGHTLY_130_END..HEAD
|
|
267
|
+ ```
|
|
268
|
+- [ ] Open MR
|
|
269
|
+- [ ] Merge
|
|
270
|
+- [ ] Sign/Tag `HEAD` of the merged `tor-browser` branch:
|
|
271
|
+ - In **tor-browser.git**, checkout the `-2` rapid `tor-browser` branch
|
|
272
|
+ - In **tor-browser-build.git**, run signing script:
|
|
273
|
+ ```bash
|
|
274
|
+ ./tools/browser/sign-tag.torbrowser rapid build1
|
|
275
|
+ ```
|
|
276
|
+ - [ ] Push tag to `upstream` |