[PATCH 0/3] Clean `rustfmt` formatting and define imports style

[PATCH 0/3] Clean `rustfmt` formatting and define imports style

[Miguel Ojeda]

Hi Linus,

Please see these commits, especially the documentation one. It is a
follow-up of the discussion on `rustfmt`.

If you are OK with it, please pick them up for -rc1 -- this should make
CIs green and let people work easily after -rc1, which would help even
if we decide to do something differently later on.

I can send a quick PR if you prefer.

Thanks!

Miguel Ojeda (3):
  docs: rust: add section on imports formatting
  rust: alloc: employ a trailing comment to keep vertical layout
  rust: cpufreq: fix formatting

 Documentation/rust/coding-guidelines.rst | 75 ++++++++++++++++++++++++
 rust/kernel/alloc/kvec.rs                |  2 +-
 rust/kernel/cpufreq.rs                   |  3 +-
 3 files changed, 77 insertions(+), 3 deletions(-)

--
2.51.0

[PATCH 1/3] docs: rust: add section on imports formatting

[Miguel Ojeda]

`rustfmt`, by default, formats imports in a way that is prone to conflicts
while merging and rebasing, since in some cases it condenses several
items into the same line.

For instance, Linus mentioned [1] that the following case:

    use crate::{
        fmt,
        page::AsPageIter,
    };

is compressed by `rustfmt` into:

    use crate::{fmt, page::AsPageIter};

which is undesirable.

Similarly, `rustfmt` may put several items in the same line even if the
braces span already multiple lines, e.g.:

    use kernel::{
        acpi, c_str,
        device::{property, Core},
        of, platform,
    };

The options that control the formatting behavior around imports are
generally unstable, and `rustfmt` releases do not allow to use nightly
features, unlike the compiler and other Rust tooling [2].

For the moment, we can introduce a workaround to prevent `rustfmt`
from compressing the example above -- the "trailing empty comment":

    use crate::{
        fmt,
        page::AsPageIter, //
    };

which is reminiscent of the trailing comma behavior in other formatters.
We already used empty comments for formatting purposes in the past,
e.g. in commit b9b701fce49a ("rust: clarify the language unstable features
in use").

In addition, `rustfmt` actually reformats with a vertical layout (i.e. it
does not put two items in the same line) when seeing such a comment,
i.e. it doesn't just preserve the formatting, which is good in the sense
that we can use it to easily reformat some imports, since it matches
the style we generally want to have.

A Git merge driver would help (suggested by Gary and Wedson), though
maintainers would need to set it up, the diffs would still be larger
and the formatting rules for imports would remain hard to predict.

Thus document the style that we will follow in the coding guidelines
by introducing a new section and explain how the trailing empty comment
works there too.

We discussed the issue with upstream Rust in our usual Rust <-> Rust
for Linux meeting [3], and there have also been a few other discussions
in parallel in issues [4][5] and Zulip [6]. We will see what happens,
but upstream Rust has already created a subteam of `rustfmt` to try
to overcome the bandwidth issue [7], which is a good signal, and some
organization work has already started (e.g. tracking issues). We will
continue our discussions with them about it.

Cc: Caleb Cartwright <caleb.cartwright@outlook.com>
Cc: Yacin Tmimi <yacintmimi@gmail.com>
Cc: Manish Goregaokar <manishsmail@gmail.com>
Cc: Deadbeef <ent3rm4n@gmail.com>
Cc: Cameron Steffen <cam.steffen94@gmail.com>
Cc: Jieyou Xu <jieyouxu@outlook.com>
Link: https://lore.kernel.org/all/CAHk-=wgO7S_FZUSBbngG5vtejWOpzDfTTBkVvP3_yjJmFddbzA@mail.gmail.com/ [1]
Link: https://github.com/rust-lang/rustfmt/issues/4884 [2]
Link: https://hackmd.io/iSCyY3JTTz-g8YM-nnzTTA [3]
Link: https://github.com/rust-lang/rustfmt/issues/4991 [4]
Link: https://github.com/rust-lang/rustfmt/issues/3361 [5]
Link: https://rust-lang.zulipchat.com/#narrow/channel/392734-council/topic/rustfmt.20maintenance/near/543815381 [6]
Link: https://github.com/rust-lang/team/pull/2017 [7]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
---
 Documentation/rust/coding-guidelines.rst | 75 ++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

diff --git a/Documentation/rust/coding-guidelines.rst b/Documentation/rust/coding-guidelines.rst
index 6ff9e754755d..3198be3a6d63 100644
--- a/Documentation/rust/coding-guidelines.rst
+++ b/Documentation/rust/coding-guidelines.rst
@@ -38,6 +38,81 @@ Like ``clang-format`` for the rest of the kernel, ``rustfmt`` works on
 individual files, and does not require a kernel configuration. Sometimes it may
 even work with broken code.
 
+Imports
+~~~~~~~
+
+``rustfmt``, by default, formats imports in a way that is prone to conflicts
+while merging and rebasing, since in some cases it condenses several items into
+the same line. For instance:
+
+.. code-block:: rust
+
+	// Do not use this style.
+	use crate::{
+	    example1,
+	    example2::{example3, example4, example5},
+	    example6, example7,
+	    example8::example9,
+	};
+
+Instead, the kernel uses a vertical layout that looks like this:
+
+.. code-block:: rust
+
+	use crate::{
+	    example1,
+	    example2::{
+	        example3,
+	        example4,
+	        example5, //
+	    },
+	    example6,
+	    example7,
+	    example8::example9, //
+	};
+
+That is, each item goes into its own line, and braces are used as soon as there
+is more than one item in a list.
+
+The trailing empty comment allows to preserve this formatting. Not only that,
+``rustfmt`` will actually reformat imports vertically when the empty comment is
+added. That is, it is possible to easily reformat the original example into the
+expected style by running ``rustfmt`` on an input like:
+
+.. code-block:: rust
+
+	// Do not use this style.
+	use crate::{
+	    example1,
+	    example2::{example3, example4, example5, //
+	    },
+	    example6, example7,
+	    example8::example9, //
+	};
+
+The trailing empty comment works for nested imports, as shown above, as well as
+for single item imports -- this can be useful to minimize diffs within patch
+series:
+
+.. code-block:: rust
+
+	use crate::{
+	    example1, //
+	};
+
+The trailing empty comment works in any of the lines within the braces, but it
+is preferred to keep it in the last item, since it is reminiscent of the
+trailing comma in other formatters. Sometimes it may be simpler to avoid moving
+the comment several times within a patch series due to changes in the list.
+
+There may be cases where exceptions may need to be made, i.e. none of this is
+a hard rule. There is also code that is not migrated to this style yet, but
+please do not introduce code in other styles.
+
+Eventually, the goal is to get ``rustfmt`` to support this formatting style (or
+a similar one) automatically in a stable release without requiring the trailing
+empty comment. Thus, at some point, the goal is to remove those comments.
+
 
 Comments
 --------
-- 
2.51.0

[PATCH 2/3] rust: alloc: employ a trailing comment to keep vertical layout

[Miguel Ojeda]

Apply the formatting guidelines introduced in the previous commit to
make the file `rustfmt`-clean again.

Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
---
 rust/kernel/alloc/kvec.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rust/kernel/alloc/kvec.rs b/rust/kernel/alloc/kvec.rs
index e94aebd084c8..ac8d6f763ae8 100644
--- a/rust/kernel/alloc/kvec.rs
+++ b/rust/kernel/alloc/kvec.rs
@@ -9,7 +9,7 @@
 };
 use crate::{
     fmt,
-    page::AsPageIter,
+    page::AsPageIter, //
 };
 use core::{
     borrow::{Borrow, BorrowMut},
-- 
2.51.0

[PATCH 3/3] rust: cpufreq: fix formatting

[Miguel Ojeda]

We do our best to keep the repository `rustfmt`-clean, thus run the tool
to fix the formatting issue.

Link: https://docs.kernel.org/rust/coding-guidelines.html#style-formatting
Link: https://rust-for-linux.com/contributing#submit-checklist-addendum
Fixes: f97aef092e19 ("cpufreq: Make drivers using CPUFREQ_ETERNAL specify transition latency")
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
---
 rust/kernel/cpufreq.rs | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/rust/kernel/cpufreq.rs b/rust/kernel/cpufreq.rs
index 21b5b9b8acc1..1a555fcb120a 100644
--- a/rust/kernel/cpufreq.rs
+++ b/rust/kernel/cpufreq.rs
@@ -38,8 +38,7 @@
 const CPUFREQ_NAME_LEN: usize = bindings::CPUFREQ_NAME_LEN as usize;
 
 /// Default transition latency value in nanoseconds.
-pub const DEFAULT_TRANSITION_LATENCY_NS: u32 =
-        bindings::CPUFREQ_DEFAULT_TRANSITION_LATENCY_NS;
+pub const DEFAULT_TRANSITION_LATENCY_NS: u32 = bindings::CPUFREQ_DEFAULT_TRANSITION_LATENCY_NS;
 
 /// CPU frequency driver flags.
 pub mod flags {
-- 
2.51.0

Re: [PATCH 3/3] rust: cpufreq: fix formatting

[Viresh Kumar]

On 10-10-25, 19:43, Miguel Ojeda wrote:
> We do our best to keep the repository `rustfmt`-clean, thus run the tool
> to fix the formatting issue.
> 
> Link: https://docs.kernel.org/rust/coding-guidelines.html#style-formatting
> Link: https://rust-for-linux.com/contributing#submit-checklist-addendum
> Fixes: f97aef092e19 ("cpufreq: Make drivers using CPUFREQ_ETERNAL specify transition latency")
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
> ---
>  rust/kernel/cpufreq.rs | 3 +--
>  1 file changed, 1 insertion(+), 2 deletions(-)
> 
> diff --git a/rust/kernel/cpufreq.rs b/rust/kernel/cpufreq.rs
> index 21b5b9b8acc1..1a555fcb120a 100644
> --- a/rust/kernel/cpufreq.rs
> +++ b/rust/kernel/cpufreq.rs
> @@ -38,8 +38,7 @@
>  const CPUFREQ_NAME_LEN: usize = bindings::CPUFREQ_NAME_LEN as usize;
>  
>  /// Default transition latency value in nanoseconds.
> -pub const DEFAULT_TRANSITION_LATENCY_NS: u32 =
> -        bindings::CPUFREQ_DEFAULT_TRANSITION_LATENCY_NS;
> +pub const DEFAULT_TRANSITION_LATENCY_NS: u32 = bindings::CPUFREQ_DEFAULT_TRANSITION_LATENCY_NS;
>  
>  /// CPU frequency driver flags.
>  pub mod flags {

Acked-by: Viresh Kumar <viresh.kumar@linaro.org>

-- 
viresh

Re: [PATCH 0/3] Clean `rustfmt` formatting and define imports style

[Benno Lossin]

On Fri Oct 10, 2025 at 7:43 PM CEST, Miguel Ojeda wrote:
> Hi Linus,
>
> Please see these commits, especially the documentation one. It is a
> follow-up of the discussion on `rustfmt`.
>
> If you are OK with it, please pick them up for -rc1 -- this should make
> CIs green and let people work easily after -rc1, which would help even
> if we decide to do something differently later on.
>
> I can send a quick PR if you prefer.
>
> Thanks!
>
> Miguel Ojeda (3):
>   docs: rust: add section on imports formatting
>   rust: alloc: employ a trailing comment to keep vertical layout
>   rust: cpufreq: fix formatting
>
>  Documentation/rust/coding-guidelines.rst | 75 ++++++++++++++++++++++++
>  rust/kernel/alloc/kvec.rs                |  2 +-
>  rust/kernel/cpufreq.rs                   |  3 +-
>  3 files changed, 77 insertions(+), 3 deletions(-)

For the series:

Reviewed-by: Benno Lossin <lossin@kernel.org>

---
Cheers,
Benno

Re: [PATCH 0/3] Clean `rustfmt` formatting and define imports style

[Miguel Ojeda]

On Fri, Oct 10, 2025 at 7:44 PM Miguel Ojeda <ojeda@kernel.org> wrote:
>
> Hi Linus,
>
> Please see these commits, especially the documentation one. It is a
> follow-up of the discussion on `rustfmt`.
>
> If you are OK with it, please pick them up for -rc1 -- this should make
> CIs green and let people work easily after -rc1, which would help even
> if we decide to do something differently later on.
>
> I can send a quick PR if you prefer.
>
> Thanks!

Since I didn't hear anything, I will send you the PR after tomorrow's
linux-next.

Applied to `rust-fixes` (plus one I just sent to the list) -- thanks everyone!

Cheers,
Miguel