move modules from kebab-case to snake_case #14439

DSchroer · 2024-08-21T19:48:18Z

What does this PR try to resolve?

It is currently unclear reading the docs how files should be named. RFC 430 is clear on crates and module names, kebab-case is never mentioned and while there are historical considerations, we should guide new development towards snake_case. We should align the documented defaults to that RFC.

How should we test and review this PR?

Review the docs and determine if we view value in the change.

rustbot · 2024-08-21T19:48:23Z

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @ehuss (or someone else) some time within the next two weeks.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

@rustbot author: the review is finished, PR author should check the comments and take action accordingly
@rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

epage · 2024-08-21T20:01:46Z

src/doc/src/guide/project-layout.md

+│       ├── named_executable.rs
+│       ├── another_executable.rs
+│       └── multi_file_executable/


I believe this would have end-user affects, making the default binary names use _ when the status quo is for binaries to use -.

As these are not just mod names but build target names, i would be inclined to leave all of these as -

ehuss · 2024-08-21T20:28:04Z

Thanks for the PR! I think there may be some confusion, as these filenames do not represent crate names, they are target names. Considering that there isn't a standard for how those should be named, I'm disinclined to change these here. Indeed, cargo's own repository makes use of hyphen in most places.

DSchroer · 2024-08-22T12:27:14Z

Considering that there isn't a standard for how those should be named, I'm disinclined to change these here. Indeed, cargo's own repository makes use of hyphen in most places.

Should we call that out in this page then? I am happy with kebab-case for build targets as they do seem out of scope from that RFC. However we should spell it out to avoid future confusion.

DSchroer · 2024-08-22T12:43:35Z

I have tried to add some clarity by explicitly stating my current understanding here. What do you think?

One thing I debated was if using a single word for targets should be recommended but that does not feel right.

epage · 2024-08-22T14:22:33Z

src/doc/src/guide/project-layout.md

@@ -48,6 +48,8 @@ files, place a `main.rs` file along with the extra [*modules*][def-module]
 within a subdirectory of the `src/bin`, `examples`, `benches`, or `tests`
 directory. The name of the executable will be the directory name.

+Binaries, examples, benches and integration tests follow `kebab-case` naming style. Modules within those targets are `snake_case` following the [Rust standard](https://rust-lang.github.io/rfcs/0430-finalizing-naming-conventions.html).


This is likely best left to a style guide, with us finding an appropriate place to link out to it.

Is there a style guide that makes sense to use?

The way I see it, right now no one in the rust ecosystem directly says that build targets are kebab-case. This document is the closest but it is not clear.

DSchroer · 2024-08-22T18:04:39Z

Are cargo targets a cargo concept? If so can we define the naming convention somewhere here in the cargo docs that says those targets should be kebab-case?

weihanglo · 2024-08-23T01:20:43Z

src/doc/src/guide/project-layout.md

In reply to #14439 (comment):

Are cargo targets a cargo concept?

Yes. See https://doc.rust-lang.org/nightly/cargo/reference/cargo-targets.html.

If so can we define the naming convention somewhere here in the cargo docs that says those targets should be kebab-case?

What's the benefit of it?

The thing is without a codified standard its hard to enforce. So people will start drifting and you will end up with multiple groups doing different things. If it becomes part of the docs then its easier to PR lints into Clippy in order to enable automatic enforcement for projects and makes the ecosystem easier and more coherent.

Thank you for explaining that :)

If it becomes part of the docs then its easier to PR lints into Clippy in order to enable automatic enforcement for projects and makes the ecosystem easier and more coherent.

I suspect this lint should live in cargo, not clippy.

That's fair. However we still need to spell out the rule in some docs first and I think this is the place for it.

I disagree that this is the place for it.

Also, even better than documenting this is to lint for it. If we have specific naming recommendations, we can use #12235 (unstable implementation is in place) to lint for naming like rustc does for functions, structs, etc.

Also, even better than documenting this is to lint for it.

100% agree. However you end up in a chicken and egg problem. If I propose a semantic lint like this with no docs to support it, then I will end up with a really hard time getting it merged. So its just a first step here to remove an ambiguous situation.

So where specifically should I try to put this?

cargo/src/cargo/core/workspace.rs

Line 1205 in d7bffc3

pub fn emit_lints(&self, pkg: &Package, path: &Path) -> CargoResult<()> {

https://github.com/rust-lang/cargo/blob/master/src/cargo/util/lints.rs

https://github.com/rust-lang/cargo/tree/master/tests/testsuite/lints

src/doc/src/guide/project-layout.md

epage · 2025-03-31T14:20:37Z

Would you be up for cleaning up the commits for how you would prefer this to be merged?

DSchroer · 2025-03-31T23:20:05Z

Updated to a single squashed commit.

Update cargo 17 commits in a6c604d1b8a2f2a8ff1f3ba6092f9fda42f4b7e9..0e93c5bf6a1d5ee7bc2af63d1afb16cd28793601 2025-03-26 18:11:00 +0000 to 2025-04-05 00:00:24 +0000 - chore(deps): bump openssl from 0.10.71 to 0.10.72 (rust-lang/cargo#15394) - chore(ci): restore cargo-util semver check (rust-lang/cargo#15389) - docs(changelog): polish changelog items (rust-lang/cargo#15379) - chore(deps): update msrv (1 version) to v1.86 (rust-lang/cargo#15381) - chore: add aarch64 linux runner (rust-lang/cargo#15077) - Added `build_directory` field to cargo metadata output (rust-lang/cargo#15377) - chore(deps): update rust crate rusqlite to 0.34.0 (rust-lang/cargo#15373) - Prevent undeclared public network access (rust-lang/cargo#15368) - rename the `author` field to be `authors` in book.toml (rust-lang/cargo#15362) - move modules from kebab-case to snake_case (rust-lang/cargo#14439) - chore: bump to 0.89.0; update changelog (rust-lang/cargo#15372) - docs(unstable): update `-Zrustdoc-depinfo` tracking issue link (rust-lang/cargo#15371) - fix(tree): Make output more deterministic (rust-lang/cargo#15369) - feat: rustdoc depinfo rebuild detection via -Zrustdoc-depinfo (rust-lang/cargo#15359) - Rename the gc config table (rust-lang/cargo#15367) - Revert "Temporarily ignore cargo_test_doctest_xcompile_ignores" (rust-lang/cargo#15357) - Don't canonicalize executable path in `cargo_exe` (rust-lang/cargo#15355) r? ghost

rustbot assigned ehuss Aug 21, 2024

rustbot added A-documenting-cargo-itself Area: Cargo's documentation S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 21, 2024

cristian-sandru approved these changes Aug 21, 2024

View reviewed changes

epage reviewed Aug 21, 2024

View reviewed changes

epage reviewed Aug 22, 2024

View reviewed changes

DSchroer requested a review from epage August 22, 2024 20:01

weihanglo reviewed Aug 23, 2024

View reviewed changes

ehuss added the I-nominated-to-discuss To be discussed during issue triage on the next Cargo team meeting label Mar 15, 2025

ehuss added this to Cargo status tracker Mar 18, 2025

ehuss moved this to Nominated in Cargo status tracker Mar 18, 2025

joshtriplett reviewed Mar 25, 2025

View reviewed changes

src/doc/src/guide/project-layout.md Outdated Show resolved Hide resolved

ehuss removed the I-nominated-to-discuss To be discussed during issue triage on the next Cargo team meeting label Mar 25, 2025

docs(project-layout): add note on recommended target naming

f8984e1

DSchroer force-pushed the layout-module-names branch from 3698b81 to f8984e1 Compare March 31, 2025 23:19

epage approved these changes Mar 31, 2025

View reviewed changes

epage enabled auto-merge March 31, 2025 23:39

epage added this pull request to the merge queue Mar 31, 2025

Merged via the queue into rust-lang:master with commit 58bab51 Apr 1, 2025
21 checks passed

weihanglo mentioned this pull request Apr 6, 2025

Update cargo rust-lang/rust#139439

Merged

rustbot added this to the 1.88.0 milestone Apr 6, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

move modules from kebab-case to snake_case #14439

move modules from kebab-case to snake_case #14439

DSchroer commented Aug 21, 2024 •

edited

Loading

rustbot commented Aug 21, 2024

epage Aug 21, 2024

ehuss commented Aug 21, 2024

DSchroer commented Aug 22, 2024

DSchroer commented Aug 22, 2024

epage Aug 22, 2024

DSchroer Aug 22, 2024

DSchroer Aug 22, 2024

DSchroer commented Aug 22, 2024 •

edited

Loading

weihanglo Aug 23, 2024 •

edited

Loading

DSchroer Aug 31, 2024

weihanglo Sep 17, 2024

epage Sep 17, 2024

DSchroer Sep 23, 2024

epage Sep 23, 2024

DSchroer Sep 23, 2024

DSchroer Sep 23, 2024

epage Sep 23, 2024

epage commented Mar 31, 2025

DSchroer commented Mar 31, 2025

move modules from kebab-case to snake_case #14439

move modules from kebab-case to snake_case #14439

Conversation

DSchroer commented Aug 21, 2024 • edited Loading

What does this PR try to resolve?

How should we test and review this PR?

rustbot commented Aug 21, 2024

Choose a reason for hiding this comment

ehuss commented Aug 21, 2024

DSchroer commented Aug 22, 2024

DSchroer commented Aug 22, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DSchroer commented Aug 22, 2024 • edited Loading

weihanglo Aug 23, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

epage commented Mar 31, 2025

DSchroer commented Mar 31, 2025

DSchroer commented Aug 21, 2024 •

edited

Loading

DSchroer commented Aug 22, 2024 •

edited

Loading

weihanglo Aug 23, 2024 •

edited

Loading