Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
wants to merge 4 commits into from

Conversation

RalfJung
Copy link
Member

@RalfJung RalfJung commented Dec 21, 2024

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.

@rustbot rustbot added the S-waiting-on-review Status: The marked PR is awaiting review from a maintainer label Dec 21, 2024
@joshtriplett
Copy link
Member

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
Copy link
Member Author

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
Copy link
Member Author

@rustbot labels +I-lang-nominated

@joshtriplett
Copy link
Member

@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 traviscross added the S-waiting-on-team Status: This is waiting for action from some team. label Dec 31, 2024
@traviscross
Copy link
Contributor

traviscross commented Dec 31, 2024

As some archaeology, this went in with:

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:

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:

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
Copy link
Member

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
Copy link
Contributor

@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.

Co-authored-by: Josh Triplett <[email protected]>
Co-authored-by: Josh Triplett <[email protected]>
@rustbot
Copy link
Collaborator

rustbot commented Mar 9, 2025

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

@ehuss
Copy link
Contributor

ehuss commented Mar 13, 2025

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
Copy link
Contributor

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
Copy link
Contributor

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
S-waiting-on-review Status: The marked PR is awaiting review from a maintainer S-waiting-on-team Status: This is waiting for action from some team.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants