modules: describe both module filename styles without giving a clear preference

[RalfJung]

There's currently no clear consensus on which filename style to use for modules, and many people have a style tha mixes both options. So let's make the reference just describe the facts, without saying which variant is preferred.

Also see the discussion on IRLO.

[joshtriplett]

I think changing the expressed preference would require a consensus to change it. There was an intentional decision in 2018 to try to migrate towards the Rust 2018 style.

[RalfJung]

I didn't realize that this was an intentional decision. There's little other indication of a goal of pushing the ecosystem towards the 2018 style. Not even the compiler itself was ever systematically adjusted.

So, that would be a t-lang FCP then?

[RalfJung]

@rustbot labels +I-lang-nominated

[joshtriplett]

@RalfJung IIRC, in 2018 when we designed the new module system, it was at that time an intentional decision to pointedly present it as "the new way" by contrast with "the old way". We didn't particularly push people to switch.

I'm not suggesting that we would necessarily object to this proposal, but I do think it's fair to say that this proposal represents a change in recommendations, and it probably warrants at least a discussion.

[traviscross]

As some archaeology, this went in with:

• Document mod.rs changes. #450

At the time, @ehuss said:

I wouldn't say it is deprecated. The RFC explicitly says "The use of mod.rs continues to be allowed without any deprecation." To me, deprecated usually implies a lint that triggers, but in this case not even the edition-idiom lints recommend this. I carefully chose to say it is "encouraged" though I don't think anyone has officially established even that.

The tracking issue, where the FCP happened, was:

• (Modules) Tracking issue for the mod.rs changes rust#53125

On that thread, Josh said:

The intention is to primarily point people to foo.rs. We want to keep foo/mod.rs for compatibility, so this change doesn't break existing projects. And we can provide appropriate lints (for people who want to write idiomatic Rust 2018 code) that encourage renaming the files accordingly, to help migrate the ecosystem. So I wouldn't expect this to bifurcate the ecosystem.

There's also some discussion between then-lang members suggesting that deprecation would have run into blocking objections.

The RFC was:

• RFC: Clarify and streamline paths and visibility rfcs#2126

What that RFC says specifically is:

The use of mod.rs continues to be allowed without any deprecation. It is expected that tooling like Clippy will push for at least style consistency within a project, and perhaps eventually across the ecosystem.