Book: Steps in Cargo Workspaces is not the best practice and can cause confusion

[upsuper]

In the current book (actually, both second edition and 2018 edition), the steps in 14.3 Cargo Workspaces is basically:

$ mkdir add
$ cd add
$ cargo new adder
$ cargo new add-one --lib

This is unfortunate, because the two cargo new would create two independent git repo, which is apparently not the best practice.

I pretty much believe the git repo should be on the workspace as a whole, which is what most multi-crate Rust projects do nowadays.

This is especially unfortunate if a reader is not familiar with git. They would start committing into two independent repos, and when others tell them that they should be in a single repo, there are only like three options:

1. ruin history of one repo and merge them into a single repo
2. use submodule which adds much complexity
3. do something complicated to merge the two repo into one by merging so that history of both are preserved

None of them is great.

The book should probably teach people to git init on the workspace directory, or alternatively tell them to create the second crate inside the first (rather than having them on the same level). The latter is probably better, and is used by many projects in practice. That would also teach people how to "upgrade" an existing crate into a workspace, which should be way more common than creating a workspace from the very beginning.

[carols10cents]

Cargo doesn't create a new git repo if you run cargo new inside a git repo. We also don't require readers of the book to use git or any version control, nor do we explain what version control is, let alone best practices for using it.

I think this sort of documentation would be better in the Cargo book, possibly by splitting this section out into its own section that shows up in the table of contents and expanding the section to include the procedure of upgrading an existing crate to a workspace and discussing version control best practices.

[upsuper]

The book doesn't mention creating git repo in the workspace in the steps, while cargo new does create git repo by default if it's not in a git repo, and thus that section is confusing.

If this document should be better in the Cargo book, the Rust book should probably not mention workspace at all, as it confuses newcomers.

I raised this because I did see people doing wrong thing in the way I mentioned while they are just trying to follow the steps in the book.

[helinwang]

I had the same question while reading that chapter. The main question for me is how to check in the workspace, since if following the chapter the crates are version controlled but the workspace is not.

@upsuper can you let me know how to do "alternatively tell them to create the second crate inside the first (rather than having them on the same level)."?

Do you mean do not create a workspace at all, and simply create the second crate inside the first?

Can you point me to some projects in Github using this approach?

[upsuper]

Do you mean do not create a workspace at all, and simply create the second crate inside the first?

Kind of yes. You just run cargo new in the directory of the existing crate.

You would still need to tweak Cargo.toml of the existing crate to include a [workspace] section to actually form a workspace, but everything else would work as expected.

Can you point me to some projects in Github using this approach?

• rand: https://github.com/rust-random/rand
• regex: https://github.com/rust-lang/regex
• crossbeam: https://github.com/crossbeam-rs/crossbeam
• parking_lot: https://github.com/Amanieu/parking_lot

Just to name a few popular ones.

[helinwang]

Thanks, @upsuper ! The repos you listed are very interesting.

If you don't mind me make this thread elongated, what is the benefit of having multiple crates vs. multiple modules?
And if you are familiar with Go, is Go's sub-package more similar to Rust's sub-crate or sub-module?

[upsuper]

That sounds out of scope of this issue, and I don't have a complete answer for that as well.

[hgomersall]

I think a caveat should be added at the very least. I was quite surprised to find the git stuff inside the new crate inside the workspace and went hunting how best to handle it, coming across this page.

[hydrocortisone]

Faced with the same problem...
Wanted to make pull-request to fix, but the problem is a bit wider by my opinion.
If we change mkdir add to cargo new add then we also need to write all instructions how to clean root cargo.toml...
I'd rather create new parameter for cargo, something like cargo new add --workspace and after change the book accordingly.

[upsuper]

@steveklabnik Hey Steve, given all the comments here, would you like to revisit it and see whether it's possible to make the book less confusing and more useful here?

[mlh758]

I followed that part of the book, tinkered in a workspace, and then went to check it into git to show a coworker what I was doing and realized I had 2 git repos. I googled rust workspace in git to see if there was a common way of dealing with this and ended up here.