Project's current formatting makes it hard to contribute non-trivial changes

[regexident]

The project's current code formatting suffers from a couple of issues, affect:

tl;dr: For the sake of making contributions hassle-free it would arguably be preferable to revert to Rust's default format (as applied by rustfmt without a custom rustfmt.toml file) and used by >90% of Rust projects.

1. It uses a non-standard format

   The Rust project recommends using the default formatting configuration to ease collaboration.

2. It provides a custom rustfmt.toml file but doesn't actually use it

   While the project provides a rustfmt.toml file

   ./rustfmt.toml

   # https://github.com/rust-lang/rustfmt/blob/master/Configurations.md
   tab_spaces = 3
   fn_call_width = 120
   chain_width = 120
   max_width = 120
   fn_single_line = true

   Running cargo fmt results in 30+ reformatted files, which should not happen if the code had previously been formatted with it.

   As such it is currently impossible to have rustfmt/cargo fmt apply the same formatting as used by the project. And anybody opening a PR on the project gets a nasty surprise when they notice that their IDE auto-formatted the code (as is usually desirable) and now the semantic changes are lost in thousands of formatting changes (as it just happened to me, again).

3. The rustfmt.toml file requires nightly and is also invalid

   Further more running cargo fmt results in a bunch of warnings:

   $ cargo fmt
   
   Warning: can't set `fn_single_line = true`, unstable features are only available in nightly channel.
   Warning: can't set `fn_single_line = true`, unstable features are only available in nightly channel.
   `fn_call_width` cannot have a value that exceeds `max_width`. `fn_call_width` will be set to the same value as `max_width`
   `chain_width` cannot have a value that exceeds `max_width`. `chain_width` will be set to the same value as `max_width`
   Warning: can't set `fn_single_line = true`, unstable features are only available in nightly channel.
   `fn_call_width` cannot have a value that exceeds `max_width`. `fn_call_width` will be set to the same value as `max_width`
   `chain_width` cannot have a value that exceeds `max_width`. `chain_width` will be set to the same value as `max_width`
   `fn_call_width` cannot have a value that exceeds `max_width`. `fn_call_width` will be set to the same value as `max_width`
   `chain_width` cannot have a value that exceeds `max_width`. `chain_width` will be set to the same value as `max_width`
   `fn_call_width` cannot have a value that exceeds `max_width`. `fn_call_width` will be set to the same value as `max_width`
   `chain_width` cannot have a value that exceeds `max_width`. `chain_width` will be set to the same value as `max_width`
   `fn_call_width` cannot have a value that exceeds `max_width`. `fn_call_width` will be set to the same value as `max_width`
   `chain_width` cannot have a value that exceeds `max_width`. `chain_width` will be set to the same value as `max_width`
   

4. The project mixes CRLF and LF

   • 37 files use CRLF
   • 31 use LF.

[s-arash]

You are correct! I need to merge the byods branch before fixing formatting issues. I don't think I'll switch to the default rustfmt config though.

[regexident]

I don't think I'll switch to the default rustfmt config though.

As long as there's a corresponding rustfmt.toml provided by the repo 👍.

[mkatychev]

You can use a nightly rustfmt config values in a rust-stable codebase by sticking rustfmt.toml in a non-root dir:

rustup run nightly cargo fmt -- --config-path fmt/rustfmt.toml

[s-arash]

@mkatychev Thanks for the suggestion. I'll get to it once I get a chance to merge the BYODS work.

[regexident]

@s-arash it looks like the BYODS work got merged in the meanwhile. Any update on this?

[mkatychev]

This is a bit ancillary but you can also define your own formatting rules using topiary as well, there's rust support under the hood but this specifically allows one to apply custom formatting for ascent grammar through s-expressions:
https://topiary.tweag.io/playground/

I've been working on a formatter for OpenSCAD using topiary with great success and have been meaning to finish https://github.com/mkatychev/tree-sitter-ascent sometime this month:
Leathong/openscad-LSP#33 (comment)

[s-arash]

Thanks for the reminder @regexident! I'll get to it soon.

[s-arash]

Very cool @mkatychev, good luck!

[regexident]

Thanks for taking care of this @s-arash! 🙏

I can't reproduce the formatting on my side though, which was the main goal of is issue, so I'd be hesitant to call it resolved just yet. 😕

---

When I run cargo fmt I'm getting 57 changed files and a bunch of warnings:

Warning: Unknown configuration option `style_edition`
Warning: can't set `format_macro_bodies = false`, unstable features are only available in nightly channel.
Warning: can't set `fn_single_line = true`, unstable features are only available in nightly channel.
Warning: can't set `where_single_line = true`, unstable features are only available in nightly channel.
Warning: can't set `imports_granularity = Module`, unstable features are only available in nightly channel.
Warning: can't set `group_imports = StdExternalCrate`, unstable features are only available in nightly channel.
Warning: can't set `overflow_delimited_expr = true`, unstable features are only available in nightly channel.
Warning: can't set `match_arm_blocks = false`, unstable features are only available in nightly channel.
Warning: can't set `trailing_semicolon = false`, unstable features are only available in nightly channel.
Warning: can't set `unstable_features = true`, unstable features are only available in nightly channel.

If I run cargo +nightly fmt however it outright fails to format, bailing after this:

cargo +nightly fmt
error[internal]: left behind trailing whitespace
  --> <SNIP>/ascent/ascent_base/src/lattice/tuple.rs:19:19:1
...

error[internal]: left behind trailing whitespace
  --> <SNIP>/ascent/ascent_base/src/lattice/tuple.rs:34:34:1
...

error[internal]: left behind trailing whitespace
  --> <SNIP>/ascent/ascent_base/src/lattice/tuple.rs:39:39:1
...

error[internal]: left behind trailing whitespace
  --> <SNIP>/ascent/ascent_base/src/lattice/tuple.rs:44:44:1
...

warning: rustfmt has failed to format. See previous 4 errors.

---

This is the Rust setup I'm running the above in:

$ cargo fmt --version

rustfmt 1.7.1-stable (f6e511ee 2024-10-15)

[s-arash]

Thanks @regexident. I've fixed those. Can you check again?

[regexident]

cargo fmt stills produces 55 changed files, but cargo +nightly fmt works now (apart from producing a change in scratchpad.rs). 👍

---

Given that cargo fmt is the default way to format Rust projects (and thus probably the way most if not all your potential contributors have their IDEs configured) it might be worth documenting this unusual requirement somewhere visible though, to keep you from having to ask on PRs to "please re-format using cargo +nightly fmt". And to avoid contributors the hassle of having to re-format their PRs retro-actively.

Better yet: make rust-analyzer do the right thing by adding the following to ./vscode/settings.json and adding it to git, thus avoiding formatting mismatches before they even happen:

{
    "editor.formatOnSave": true,
    "rust-analyzer.linkedProjects": [
        "./ascent/Cargo.toml",
        "./ascent_macro_tests/Cargo.toml", // excluded in workspace
        "./ascent_tests/Cargo.toml", // excluded in workspace
        "./wasm-tests/Cargo.toml" // excluded in workspace
    ],
    "rust-analyzer.rustfmt.extraArgs": ["+nightly"]
}

(not sure what's the equivalent for RustRover)

[regexident]

FYI, I've just updated my open PRs with the new formatting. Would appreciate if you could take a look some time.