From f19ecfb64bee4c3f20012fb4251c60265cd2dd4c Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Wed, 26 Oct 2022 23:33:29 +0100 Subject: [PATCH 01/13] Style evolution --- text/0000-style-evolution.md | 91 ++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 text/0000-style-evolution.md diff --git a/text/0000-style-evolution.md b/text/0000-style-evolution.md new file mode 100644 index 00000000000..5626967bd73 --- /dev/null +++ b/text/0000-style-evolution.md @@ -0,0 +1,91 @@ +- Feature Name: style-evolution +- Start Date: 2022-10-26 +- RFC PR: [rust-lang/rfcs#0000](https://github.com/rust-lang/rfcs/pull/0000) +- Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000) + +# Summary +[summary]: #summary + +This RFC defines a mechanism for evolving the default Rust style over time +without breaking backwards compatibility, via the Rust edition mechanism. + +# Motivation +[motivation]: #motivation + +The current Rust style, as defined in the Rust Style Guide and as implemented +by rustfmt, has some stability expectations associated with it. In particular, +many projects implement continuous integration hooks that verify the style of +Rust code (such as with `cargo fmt --check`), and changes to the style would +break the CI of such projects, in addition to causing churn. + +This document proposes to evolve the current Rust style, without breaking +backwards compatibility, by tying style evolution to Rust edition. Code in Rust +2015, 2018, or 2021 will use the existing default style. Code in future +editions (Rust 2024 and onwards) may use a new style edition. + +This RFC only defines the mechanism by which we evolve the Rust style; this RFC +does *not* define any specific style changes. Future RFCs or style-guide PRs +will define future style editions. This RFC does not propose or define any +specific future style editions or other formatting changes. + +# Explanation +[explanation]: #explanation + +`rustfmt`, and `cargo fmt`, will format code according to the default Rust +style. The default Rust style varies by Rust edition. (Not every edition +changes the Rust style, and thus some editions have identical default styles; +Rust 2015, 2018, and 2021 all have the same default style.) + +By default, `rustfmt` and `cargo fmt` will use the same edition that the Rust +code itself is configured to use. `cargo fmt` will pass `rustfmt` the edition +specified in `Cargo.toml`; for direct invocation of `rustfmt`, +`rustfmt.toml`/`.rustfmt.toml` can also specify the `edition`. + +However, when transitioning between editions, projects may want to separately +make and commit the changes for 1) transitioning to a new Rust edition and 2) +transitioning to a new style edition. To allow for this, `rustfmt` also allows +configuring the style edition directly, via a separate `style_edition` +configuration option, or `--style-edition` command-line option. + +Note that rustfmt may not necessarily support all combinations of Rust edition +and style edition; in particular, it may not support using a style edition that +differs by more than one step from the Rust edition. + +The current version of the style guide will describe the latest Rust edition. +Each distinct past style will have a corresponding archived version of the +style guide. Note that archived versions of the style guide may not necessarily +document formatting for newer Rust constructs that did not exist at the time +that version of the style guide was archived. + +# Rationale and alternatives +[rationale-and-alternatives]: #rationale-and-alternatives + +We could have a completely separate configuration mechanism, unrelated to +editions. This would increase the development and testing burden of rustfmt, +and seems unlikely to provide commensurate value. This would also increase the +complexity for end users, who would have to understand two separate mechanisms +for handling forwards-compatibility and wonder how they differ. We feel that +since we're providing a mechanism similar to editions, we should make it clear +to users that it works like editions. + +We could leave out the separate configuration of style edition, and keep style +edition in lockstep with Rust edition. This would be easier to develop and +test, but would mean larger and noisier commits in projects transitioning from +one edition to another. + +We could keep the Rust style static forever, and never change it. + +We could evolve the Rust style without a backwards-compatibility mechanism. +This would result in churn in people's repositories if collaborating +developers have different versions of Rust, and would break +continuous-integration checks that check formatting. + +# Prior art +[prior-art]: #prior-art + +The Rust edition mechanism itself serves as prior art. + +# Future possibilities +[future-possibilities]: #future-possibilities + +Actual changes to the Rust style for Rust 2024 or future editions. From a64b7e89bcb6d97e612990a6a621bf535cd47800 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Wed, 26 Oct 2022 23:52:14 +0100 Subject: [PATCH 02/13] Mention `version = "Two"` as prior art --- text/0000-style-evolution.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/text/0000-style-evolution.md b/text/0000-style-evolution.md index 5626967bd73..9b8c208d08b 100644 --- a/text/0000-style-evolution.md +++ b/text/0000-style-evolution.md @@ -85,6 +85,9 @@ continuous-integration checks that check formatting. The Rust edition mechanism itself serves as prior art. +`rustfmt` has a still-unstable option `version = "Two"` to opt into new +formatting, though the exact changes this makes are not documented. + # Future possibilities [future-possibilities]: #future-possibilities From 474de4987c886fd1ca6deb6bcc71d80455e236b5 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Thu, 27 Oct 2022 12:40:45 +0100 Subject: [PATCH 03/13] Clarify handling of edition in `rustfmt` vs `cargo fmt` --- text/0000-style-evolution.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/text/0000-style-evolution.md b/text/0000-style-evolution.md index 9b8c208d08b..4ec77677e71 100644 --- a/text/0000-style-evolution.md +++ b/text/0000-style-evolution.md @@ -36,10 +36,12 @@ style. The default Rust style varies by Rust edition. (Not every edition changes the Rust style, and thus some editions have identical default styles; Rust 2015, 2018, and 2021 all have the same default style.) -By default, `rustfmt` and `cargo fmt` will use the same edition that the Rust -code itself is configured to use. `cargo fmt` will pass `rustfmt` the edition -specified in `Cargo.toml`; for direct invocation of `rustfmt`, -`rustfmt.toml`/`.rustfmt.toml` can also specify the `edition`. +Direct invocations of `rustfmt` obtain the edition used for parsing Rust code +from the `edition` option in its configuration file (`rustfmt.toml` or +`.rustfmt.toml`), or via the `--edition` command-line option; `cargo fmt` +obtains the edition from the `edition` option in `Cargo.toml` and passes it to +`rustfmt`. By default, `rustfmt` and `cargo fmt` will use the same edition for +style as the Rust edition used for parsing. However, when transitioning between editions, projects may want to separately make and commit the changes for 1) transitioning to a new Rust edition and 2) From aa55ad61b270dd893309d3e83e2fbcd99efe93f3 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Thu, 27 Oct 2022 13:21:32 +0100 Subject: [PATCH 04/13] Explicitly state that `style_edition` overrides the edition --- text/0000-style-evolution.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/text/0000-style-evolution.md b/text/0000-style-evolution.md index 4ec77677e71..0a39a4f0c09 100644 --- a/text/0000-style-evolution.md +++ b/text/0000-style-evolution.md @@ -47,7 +47,10 @@ However, when transitioning between editions, projects may want to separately make and commit the changes for 1) transitioning to a new Rust edition and 2) transitioning to a new style edition. To allow for this, `rustfmt` also allows configuring the style edition directly, via a separate `style_edition` -configuration option, or `--style-edition` command-line option. +configuration option, or `--style-edition` command-line option. `style_edition` +or `--style-edition`, if set, always overrides `edition` or `--edition` for the +purposes of styling, though `edition` or `--edition` still determines the +edition for the purposes of parsing Rust code. Note that rustfmt may not necessarily support all combinations of Rust edition and style edition; in particular, it may not support using a style edition that From 88761776fc6246354224844b22499d3ef58468dc Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Sun, 30 Oct 2022 11:22:07 +0100 Subject: [PATCH 05/13] Style evolution is 3338 --- text/{0000-style-evolution.md => 3338-style-evolution.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename text/{0000-style-evolution.md => 3338-style-evolution.md} (98%) diff --git a/text/0000-style-evolution.md b/text/3338-style-evolution.md similarity index 98% rename from text/0000-style-evolution.md rename to text/3338-style-evolution.md index 0a39a4f0c09..de21a71a032 100644 --- a/text/0000-style-evolution.md +++ b/text/3338-style-evolution.md @@ -1,6 +1,6 @@ - Feature Name: style-evolution - Start Date: 2022-10-26 -- RFC PR: [rust-lang/rfcs#0000](https://github.com/rust-lang/rfcs/pull/0000) +- RFC PR: [rust-lang/rfcs#3338](https://github.com/rust-lang/rfcs/pull/3338) - Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000) # Summary From 2f168cb5fe55ec84f2e11180d1108290d5048082 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Tue, 1 Nov 2022 11:09:13 +0100 Subject: [PATCH 06/13] Rephrase wording about style guide versions Co-authored-by: Jane Losare-Lusby --- text/3338-style-evolution.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/text/3338-style-evolution.md b/text/3338-style-evolution.md index de21a71a032..749f66f172a 100644 --- a/text/3338-style-evolution.md +++ b/text/3338-style-evolution.md @@ -56,9 +56,8 @@ Note that rustfmt may not necessarily support all combinations of Rust edition and style edition; in particular, it may not support using a style edition that differs by more than one step from the Rust edition. -The current version of the style guide will describe the latest Rust edition. -Each distinct past style will have a corresponding archived version of the -style guide. Note that archived versions of the style guide may not necessarily +The style team will maintain distinct versions of the style guide for each style +edition. Note that archived versions of the style guide may not necessarily document formatting for newer Rust constructs that did not exist at the time that version of the style guide was archived. From c42bece34975485145a5725895af98afa4f487d4 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Tue, 1 Nov 2022 13:54:14 +0100 Subject: [PATCH 07/13] Allow new style editions to start out as nightly only --- text/3338-style-evolution.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/text/3338-style-evolution.md b/text/3338-style-evolution.md index 749f66f172a..3024446ba25 100644 --- a/text/3338-style-evolution.md +++ b/text/3338-style-evolution.md @@ -56,6 +56,12 @@ Note that rustfmt may not necessarily support all combinations of Rust edition and style edition; in particular, it may not support using a style edition that differs by more than one step from the Rust edition. +New style editions will be initially introduced as nightly-only, to make them +available for testing; such nightly-only editions will produce an error if +requested in stable rustfmt. Nightly versions of style editions are subject to +change and do not provide stability guarantees. New style editions will get +stabilized contemporaneously with the corresponding Rust edition. + The style team will maintain distinct versions of the style guide for each style edition. Note that archived versions of the style guide may not necessarily document formatting for newer Rust constructs that did not exist at the time @@ -87,7 +93,8 @@ continuous-integration checks that check formatting. # Prior art [prior-art]: #prior-art -The Rust edition mechanism itself serves as prior art. +The Rust edition mechanism itself serves as prior art, as does the mechanism of +nightly features remaining subject to change until stabilization. `rustfmt` has a still-unstable option `version = "Two"` to opt into new formatting, though the exact changes this makes are not documented. From 2a5d2fa2d0ec8979095c9f56b77184b36e75091d Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Wed, 2 Nov 2022 21:17:08 +0100 Subject: [PATCH 08/13] Add link to rustfmt stability guarantee in RFC 2437 in prior art --- text/3338-style-evolution.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/text/3338-style-evolution.md b/text/3338-style-evolution.md index 3024446ba25..505f76c8fff 100644 --- a/text/3338-style-evolution.md +++ b/text/3338-style-evolution.md @@ -99,6 +99,9 @@ nightly features remaining subject to change until stabilization. `rustfmt` has a still-unstable option `version = "Two"` to opt into new formatting, though the exact changes this makes are not documented. +`rustfmt`'s stability guarantees are documented in [RFC +2437](https://github.com/rust-lang/rfcs/pull/2437/). + # Future possibilities [future-possibilities]: #future-possibilities From 7a40d947dcca61bcd818057e9c0b9e2d446a4857 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Sat, 5 Nov 2022 08:22:52 -0700 Subject: [PATCH 09/13] Note that rustfmt need not support all configuration in all style editions For instance, a configuration option might become obsolete in a new style edition if it configures something that no longer applies. --- text/3338-style-evolution.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/text/3338-style-evolution.md b/text/3338-style-evolution.md index 505f76c8fff..4ccafde4692 100644 --- a/text/3338-style-evolution.md +++ b/text/3338-style-evolution.md @@ -54,7 +54,8 @@ edition for the purposes of parsing Rust code. Note that rustfmt may not necessarily support all combinations of Rust edition and style edition; in particular, it may not support using a style edition that -differs by more than one step from the Rust edition. +differs by more than one step from the Rust edition. Similarly, rustfmt need +not support every existing configuration option in new style editions. New style editions will be initially introduced as nightly-only, to make them available for testing; such nightly-only editions will produce an error if From 0646850288febc49f560362d02bbd38f4944b077 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Wed, 16 Nov 2022 13:35:55 -0800 Subject: [PATCH 10/13] Mention tooling such as `blame.ignoreRevsFile` --- text/3338-style-evolution.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/text/3338-style-evolution.md b/text/3338-style-evolution.md index 4ccafde4692..94e0064a3f2 100644 --- a/text/3338-style-evolution.md +++ b/text/3338-style-evolution.md @@ -45,12 +45,16 @@ style as the Rust edition used for parsing. However, when transitioning between editions, projects may want to separately make and commit the changes for 1) transitioning to a new Rust edition and 2) -transitioning to a new style edition. To allow for this, `rustfmt` also allows -configuring the style edition directly, via a separate `style_edition` -configuration option, or `--style-edition` command-line option. `style_edition` -or `--style-edition`, if set, always overrides `edition` or `--edition` for the -purposes of styling, though `edition` or `--edition` still determines the -edition for the purposes of parsing Rust code. +transitioning to a new style edition. Keeping formatting changes in a separate +commit also helps tooling ignore that commit, such as with git's +`blame.ignoreRevsFile`. + +To allow for this, `rustfmt` also allows configuring the style edition +directly, via a separate `style_edition` configuration option, or +`--style-edition` command-line option. `style_edition` or `--style-edition`, if +set, always overrides `edition` or `--edition` for the purposes of styling, +though `edition` or `--edition` still determines the edition for the purposes +of parsing Rust code. Note that rustfmt may not necessarily support all combinations of Rust edition and style edition; in particular, it may not support using a style edition that From 51ec87232faea81ffb263d6a47ad5ec2bdb3e4f9 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Wed, 16 Nov 2022 16:48:39 -0800 Subject: [PATCH 11/13] Expand text about style guides for each edition, discuss new constructs --- text/3338-style-evolution.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/text/3338-style-evolution.md b/text/3338-style-evolution.md index 94e0064a3f2..d52b018d7af 100644 --- a/text/3338-style-evolution.md +++ b/text/3338-style-evolution.md @@ -67,10 +67,14 @@ requested in stable rustfmt. Nightly versions of style editions are subject to change and do not provide stability guarantees. New style editions will get stabilized contemporaneously with the corresponding Rust edition. -The style team will maintain distinct versions of the style guide for each style -edition. Note that archived versions of the style guide may not necessarily +The current version of the style guide will describe the latest Rust edition. +Each distinct past style will have a corresponding archived version of the +style guide. Note that archived versions of the style guide may not necessarily document formatting for newer Rust constructs that did not exist at the time -that version of the style guide was archived. +that version of the style guide was archived. However, each style edition will +still format all constructs valid in that Rust edition, with the style of those +constructs coming from the first subsequent style edition providing formatting +rules for that construct. # Rationale and alternatives [rationale-and-alternatives]: #rationale-and-alternatives From 80ee30d9234239c7cbaf22e65019d087c3e73d93 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Wed, 16 Nov 2022 17:00:30 -0800 Subject: [PATCH 12/13] Discuss permanent vs temporary use of old style editions --- text/3338-style-evolution.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/text/3338-style-evolution.md b/text/3338-style-evolution.md index d52b018d7af..ddc4eedee2d 100644 --- a/text/3338-style-evolution.md +++ b/text/3338-style-evolution.md @@ -87,6 +87,17 @@ for handling forwards-compatibility and wonder how they differ. We feel that since we're providing a mechanism similar to editions, we should make it clear to users that it works like editions. +We could allow style edition to vary completely independently of Rust edition. +This would, for instance, allow projects to stay on old style editions +indefinitely. However, this would substantially increase the development and +testing burden for formatting tooling, and require more complex decisions about +how old style editions format constructs that didn't exist in the corresponding +Rust edition. In general, while the Rust edition mechanism allows projects to +stay on old Rust editions, and projects doing so can similarly stay on the +corresponding old style editions, the style edition mechanism does not exist to +facilitate staying on old styles *indefinitely* while still moving forward to +newer Rust editions. + We could leave out the separate configuration of style edition, and keep style edition in lockstep with Rust edition. This would be easier to develop and test, but would mean larger and noisier commits in projects transitioning from From 5e95dbf9846eada900152e9b6173ee70fcacc33c Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Mon, 5 Dec 2022 13:56:56 -0800 Subject: [PATCH 13/13] Add tracking issue for style evolution --- text/3338-style-evolution.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/3338-style-evolution.md b/text/3338-style-evolution.md index ddc4eedee2d..79a63f18b0e 100644 --- a/text/3338-style-evolution.md +++ b/text/3338-style-evolution.md @@ -1,7 +1,7 @@ - Feature Name: style-evolution - Start Date: 2022-10-26 - RFC PR: [rust-lang/rfcs#3338](https://github.com/rust-lang/rfcs/pull/3338) -- Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000) +- Rust Issue: [rust-lang/rust#105336](https://github.com/rust-lang/rust/issues/105336) # Summary [summary]: #summary