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.

[scottmcm]

Personally, I like the argument that the reference isn't the place to say anything about which is "encouraged".

The reference is the place to say "these both work", lints and the book and such are the place to say which one you should use.

[traviscross]

@rustbot labels -I-lang-nominated

We reviewed this in lang triage today. We agreed that the 2018 lang consensus was indeed to encourage one way (foo.rs) over the other way (foo/mod.rs), while at the same time not deprecating the old way, and we did not have any consensus for changing that.

[rustbot]

☔ The latest upstream changes (possibly dda31c8) made this pull request unmergeable. Please resolve the merge conflicts.

[ehuss]

we did not have any consensus for changing that.

I'm uncertain how to interpret this. Are you saying that you do or do not want to proceed with this change? Or is there some other change you are suggesting?

My interpretation is that the current text encourages foo.rs, but does not imply a deprecation of mod.rs.

[traviscross]

We did not have any current consensus to change the prior consensus, which was to encourage foo.rs as the "new" way while not deprecating foo/mod.rs.

That is, the lang team's standing normative (in the sense of setting norms, but not in a way encoded in the language) position is what is currently written in the Reference.

[traviscross]

Thanks @RalfJung for putting this forward. We talked about this on the lang-docs call, then on the spec call. We're going to close this for a kind of stylistic reason.

In the Reference, we document the "most recent" Rust in the main flow of text, and then we document older things we support. Most prominently, this is what we do for editions. Here, it's a closer call, but given the standing lang consensus about issuing a normative (in the sense of setting norms) position on this, it falls in the same bucket for us, and so in that way, the existing text is OK.

[Kinrany]

Instead of removing the encouragement altogether, perhaps it's possible to either amend it to mention significant controversy or to replace it with an indirect encouragement that states the motivation behind the current consensus and points to its discussion?