cargo new: create README in bin crates

[jsjoeio]

This PR completes some of the work for #3506.

Changes

• create README for new binary crates as part of cargo new
• adjust tests in cargo_new to check/!check for README

Screenshots

Example of new change to cargo new:
creates a README.md for a new binary crate

Passing tests:

Failing test (safe to ignore):

Checklist

• tests are passing
• added new tests

Additional Notes

Per the original decision noted in this comment, these were the requirements (this PR accomplishes the ones that are checked):

• For a binary crate:
  • README.md that contains the text TODO: add a description of this crate's purpose and recommends using cargo install [cratename] to install the crate
• For a library crate:
  • README.md file that contains the text TODO: add a description of this crate's purpose and recommends adding the crate to one's Cargo.toml to use the crate as a dependency
  • Module-level documentation in src/lib.rs that contains the text TODO: add a description of this crate's purpose
• For a workspace crate (when you run cargo new within a workspace`):
  • Do not create README.md
  • Module-level documentation in src/lib.rs that contains the text TODO: add a description of this crate's purpose

Re: For a workspace crate (when you run cargo new within a workspace`):
- Do not create README.md

I was able to detect bin vs library crates, but I struggled to do the same for workspace crates. Open to guidance or feedback on how to detect that within the new command file.

Regarding the remaining todos, my thoughts were to accomplish them in separate PRs.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @Eh2406 (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[Eh2406]

Thank you for the PR!

The decision described here is somewhat old, for example it predates my involvement with cargo. @rust-lang/cargo what do we now thing about the plan?

[alexcrichton]

I don't personally at least remember much about the context of the original decision. I don't really have many opinions about readmes either, and I'd be fine adding templates if others feel it's a good enough idea.

[aleksator]

I am personally not convinced that we should go with the proposed solution.

I relate to the arguments provided by @sanmai-NL in this, this, this, and other comments from the original discussion, that note that we shouldn't enforce a particular readme format.

When I was reading that thread before, I decided not to work on this issue myself since there wasn't any consensus reached, despite the seeming push of "Let's just do README.md" by prominent team members.

[ehuss]

The Cargo team discussed this feature and we've decided to close this PR for now. There is some disagreement about what the Readme should contain, or even if it should be created at all.

I think the obvious solution is some kind of template system, where the user can specify their default templates to get whatever behavior they want. There are several efforts that implement templated projects, such as cargo-generate and cargo-readme. See also the tracking issue #5151 and https://internals.rust-lang.org/t/pre-rfc-cargo-templates/5056.

Ideally a proposal to add templates to cargo new would go through the RFC process, taking into consideration the motivation, design space, and impact.

Another possibility to explore is to add an interactive mode to cargo new. One idea is if cargo new is run without arguments, it could ask a series of questions to create a new project (name? Initialize a git repo? Create a library? Create a binary executable? Create a README? etc.). That might be a lighter-weight solution compared to a full template solution (that I'd probably be OK without an RFC), but the design would still need to be hashed out.

@jsjoeio if you'd be interested in exploring those routes, let us know! It might also help to know what your interest is in this feature, or what motivated this PR.

[jsjoeio]

The Cargo team discussed this feature and we've decided to close this PR for now. There is some disagreement about what the Readme should contain, or even if it should be created at all.

I knew there would be some risk in attempting this without formal approval. Makes total sense. Though I'm glad it was revisited.

Ideally a proposal to add templates to cargo new would go through the RFC process, taking into consideration the motivation, design space, and impact.

Good to know! Thank you for explaining that.

@jsjoeio if you'd be interested in exploring those routes, let us know!

I might be! It would be great to learn about the RFC process, get more involved with Rust, and potentially work with other folks to get this implemented. Let me think on it over the weekend :)

It might also help to know what your interest is in this feature, or what motivated this PR.

New to Rust, wanted to contribute. When I first tried cargo new, my eyes lite up seeing what it included for you out the gate. Note I'm coming from the JavaScript/npm init world.

I noticed it didn't include a README, found the original issue, and decided to give it shot. What motivated me?

• working on something that was high impact
• docs are important. I can tell the Rust community believes so and I personally would like to see READMEs encouraged out of the box.

Thank you to the Cargo team for discussing! @ehuss if after the weekend, I decide I want to help with this effort, what would you suggest as next steps? My thoughts:

• read and research the efforts you linked
• read about the RFC process
• draft an RFC and share with the Cargo team? (p.s. not sure where to find the Cargo team, don't see it on the Governance page)

[aleksator]

@jsjoeio Glad to hear you have the motivation to do this right!
Cargo team can be most easily reached on the Rust's Discord #cargo channel.
On the Governance page, they are under dev tools.

[jsjoeio]

Thank you @aleksator! I've thought about it and decided I do want to help with this effort. I'm going to start an RFC and go from there. I'll leave a comment on the original issue so others are aware. Thanks all for you help!

[ehuss]

what would you suggest as next steps?

Yea. The RFC repo should explain the process. Generally people start with a basic proposal and post it for the community to get initial feedback (often on internals).

don't see it on the Governance page

It is a sub-team of the dev-tools.

[jsjoeio]

Awesome, thank you! Just posted a Pre-RFC on internals.

Link for anyone interested in checking it out.