Skip to content

Commit ad307fb

Browse files
jieyouxujieyouxu
committed
Add a rustfmt-specific copy of subtree sync procedure
1 parent 51c5a47 commit ad307fb

File tree

2 files changed

+212
-0
lines changed

2 files changed

+212
-0
lines changed

‎Contributing.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -269,6 +269,10 @@ accessing the correct field on the config struct, e.g., `config.max_width()`. Mo
269269
functions have a `Config`, or one can be accessed via a visitor or context of
270270
some kind.
271271

272+
## Subtree syncs
273+
274+
Refer to [*Subtree sync procedure*](./Subtree%20sync%20procedure.md).
275+
272276

273277
[rustfmt-zulip]:
274278
https://rust-lang.zulipchat.com/#narrow/channel/357797-t-rustfmt

‎Subtree sync procedure.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# `rustfmt` subtree sync procedure
2+
3+
Note that `rustfmt` has not migrated to `josh` yet, so the git subtree sync is somewhat involved.
4+
This procedure is mostly adapted from the `clippy` subtree sync process at
5+
<https://doc.rust-lang.org/stable/clippy/development/infrastructure/sync.html>, but adapted for
6+
`rustfmt`. We are keeping a separate copy of the instructions for `rustfmt` in case `clippy` moves
7+
off of `git subtree` in the mean time (and also slightly adjusted to be `rustfmt`-specific.
8+
9+
> [!NOTE]
10+
>
11+
> Note that AFAIK, eventually both `clippy` and `rustfmt` would like to move to the `josh`-sync
12+
> workflow, just that `rustfmt` is blocked on actually doing a bidirectional sync first, while
13+
> `clippy` is sorting out some issues related to tags and git history (due to usage of `git
14+
> subtree`).
15+
16+
## Tooling
17+
18+
The `git-subtree` tooling still has a bug that prevents it from working properly with the
19+
`rust-lang/rust` repository. This means that you need to build and use a patched version of
20+
`git-subtree`.
21+
22+
> [!INFO]
23+
>
24+
> The patched version of `git-subtree` is the sources corresponding to the stale PR
25+
> <https://github.com/gitgitgadget/git/pull/493>.
26+
27+
On Linux, place `git-subtree` under `/usr/lib/git-core` (make sure to keep a backup copy of the
28+
'standard' `git-subtree`), and make sure it has proper permissions:
29+
30+
```sh
31+
$ sudo cp --backup /path/to/patched/git-subtree.sh /usr/lib/git-core/git-subtree
32+
$ sudo chmod --reference=/usr/lib/git-core/git-subtree~ /usr/lib/git-core/git-subtree
33+
$ sudo chown --reference=/usr/lib/git-core/git-subtree~ /usr/lib/git-core/git-subtree
34+
```
35+
36+
> [!INFO]
37+
>
38+
> Running `git subtree push` for the first time requires building a cache, which involves going
39+
> through the entire history of `rustfmt` once. You likely will need to increase the stack limit via
40+
>
41+
> ```sh
42+
> $ ulimit -s 60000
43+
> ```
44+
45+
> [!INFO] Git remotes The following steps assume that you have configured the `rustfmt` remote as
46+
> `upstream`, i.e.
47+
>
48+
> ```sh
49+
> $ git remote add upstream git@github.com:rust-lang/rustfmt
50+
> ```
51+
52+
## Subtree push direction: syncing changes from `rust-lang/rust` to `rustfmt`
53+
54+
> [!WARNING]
55+
>
56+
> **For this subtree-push direction, all commands described must be run within the `rust-lang/rust`
57+
> checkout.**
58+
59+
### 1. Acquire a checkout of `rust-lang/rust`
60+
61+
Either acquire a clone of `rust-lang/rust`, or if you already have a checkout, make sure the
62+
checkout is up-to-date via `git fetch`.
63+
64+
### 2. Checkout the commit from the latest available nightly
65+
66+
You can fetch the commit hash of the latest available nightly by inspecting `rustup check` output.
67+
68+
### 3. Sync changes from the `rust`-copy of `rustfmt` to your `rustfmt` fork
69+
70+
> [!WARNING]
71+
>
72+
> **Make sure to either use a fresh branch, e.g. `subtree-push`, or delete the branch beforehand**.
73+
> Changes cannot be fast forwarded and you have to run this command again.
74+
75+
```sh
76+
$ git subtree push -P src/tools/rustfmt /path/to/rustfmt/checkout subtree-push
77+
```
78+
79+
Most of the time, you will need to create a **merge commit** in the `rustfmt` repository. Note that
80+
this must be done in the subtree repo (i.e. `rustfmt` repo) and not in the `rust`-copy of `rustfmt`.
81+
82+
Assuming the `upstream` remote is the `rust-lang/rust` remote:
83+
84+
```sh
85+
$ git fetch upstream
86+
$ git switch subtree-push
87+
$ git merge upstream/main --no-ff
88+
```
89+
90+
> [!WARNING]
91+
>
92+
> You may have to manually resolve certain merge conflicts. Pay extra attention when resolving them,
93+
> since it's easy to accidentally resolve the conflict in incorrect ways.
94+
95+
> [!TIP]
96+
>
97+
> Subtree syncs are one of the rare occasions where a merge commit is allowed in a PR.
98+
99+
### 4. Bump the nightly toolchain version in the `rustfmt` repository
100+
101+
Using the same latest nightly date (that you can obtain by inspecting `rustup check` output),
102+
manually edit `rust-toolchain`:
103+
104+
```diff
105+
[toolchain]
106+
-channel = "nightly-2025-04-02"
107+
+channel = "nightly-$LATEST_NIGHTLY_DATE"
108+
components = ["llvm-tools", "rustc-dev"]
109+
```
110+
111+
Substituting `$LATEST_NIGHTLY_DATE` with the latest nightly date.
112+
113+
Create a separate commit dedicated to making the `rust-toolchain` change. You can use [the following
114+
commit message template](#rust-toolchain-bump-commit-message-template).
115+
116+
#### `rust-toolchain` bump commit message template
117+
118+
```text
119+
chore: bump rustfmt toolchain to nightly-$LATEST_NIGHTLY_DATE
120+
121+
Bumping the toolchain version as part of a git subtree push.
122+
123+
current toolchain (nightly-$CURRENT_NIGHTLY_DATE):
124+
- $CURRENT_NIGHTLY_VERSION-nightly ($CURRENT_NIGHTLY_HASH $CURRENT_NIGHTLY_DATE)
125+
126+
latest toolchain (nightly-$LATEST_NIGHTLY_DATE):
127+
- $LATEST_NIGHTLY_VERSION-nightly ($LATEST_NIGHTLY_HASH $LATEST_NIGHTLY_DATE)
128+
```
129+
130+
Substituting the placeholders with the right information.
131+
132+
> [!EXAMPLE]
133+
>
134+
> Example bump commit message:
135+
>
136+
> ```text
137+
> chore: bump rustfmt toolchain to nightly-2025-10-07
138+
>
139+
> Bumping the toolchain version as part of a git subtree push.
140+
>
141+
> current toolchain (nightly-2025-04-02): - 1.88.0-nightly (e2014e876 2025-04-01)
142+
>
143+
> latest toolchain (nightly-2025-10-07): - 1.92.0-nightly (f6aa851db 2025-10-07)
144+
> ```
145+
146+
### 5. Open a PR against `rustfmt`
147+
148+
And wait for the sync PR to be merged. The `rustfmt` maintainers will run Diff Check against the PR
149+
to catch any unexpected formatting changes. Once Diff Check failures are investigated and are
150+
resolved, the PR can then be merged.
151+
152+
For the PR:
153+
154+
- Use the title `subtree-push nightly-$LATEST_NIGHTLY_DATE` for consistency with previous
155+
subtree-pushes.
156+
- Include a copy of the bump commit message in the PR description for quick reference. Feel free to
157+
include additional notes that might be helpful for the maintainers when reviewing.
158+
159+
> [!EXAMPLE]
160+
>
161+
> Example subtree-push PR title and description:
162+
>
163+
> **PR title**: `subtree-push nightly-2025-10-07`
164+
>
165+
> **PR description**:
166+
>
167+
> ```text
168+
> Bumping the toolchain version as part of a git subtree push.
169+
>
170+
> current toolchain (nightly-2025-04-02):
171+
> - 1.88.0-nightly (e2014e876 2025-04-01)
172+
>
173+
> latest toolchain (nightly-2025-10-07):
174+
> - 1.92.0-nightly (f6aa851db 2025-10-07)
175+
> ```
176+
177+
> [!WARNING]
178+
>
179+
> Make sure to immediately follow-up with a subtree-pull direction, syncing `rustfmt` to
180+
> `rust-lang/rust`. We need the {subtree-push, subtree-pull} directions to be performed in
181+
> lock-step, to minimize any changes in between that makes the logistics more complex.
182+
183+
## Subtree pull direction: syncing from `rustfmt` to `rust-lang/rust`
184+
185+
> [!WARNING]
186+
>
187+
> For this **subtree-pull** direction, all commands must also be performed within the
188+
> `rust-lang/rust` checkout.
189+
190+
### 1. Make sure latest `main` of `rust-lang/rust` is checked out
191+
192+
### 2. Sync `rustfmt` `main` to the `rust`-copy of `rustfmt`
193+
194+
```sh
195+
$ git switch -c rustfmt-subtree-update
196+
$ git subtree pull -P src/tools/rustfmt /path/to/rustfmt/checkout main
197+
```
198+
199+
### 3. Open a PR against `rust-lang/rust`
200+
201+
Use the PR title
202+
203+
> `rustfmt` subtree update
204+
205+
so that `triagebot` will not warn against the PR containing a merge commit, and makes it easy for
206+
`rustfmt` maintainers to discover.
207+
208+
Back link to the `rustfmt` subtree-push PR as helpful context.

0 commit comments

Comments
 (0)