Encourage the use of the repository field in Cargo.toml

[szabgab]

Problem

Having the repository field in Cargo.toml of an open source Rust project will make it easier to contribute to the project.
According to my analysis on Rust-Digger, 19.03% of the crates don't have the repository field.

Some of those ~ 2.23% use the homepage field to link to the repository. It is better than nothing, but ideally people would use the repository field. See stats: https://rust-digger.code-maven.com/stats

Proposed Solution

Adding

# repository = ""

to the generated Cargo.toml file will probably encourage more people to enable it and use it to link to the repository.

In addition including a commented out link to the documentation of the manifest would also help https://doc.rust-lang.org/cargo/reference/manifest.html

Finally, cargo publish might give a warning if the repository field is missing or if it is empty

Notes

No response

[epage]

Another important reason for the repository field is for checking that the publish matches the code. We improved these checks recently (see #13695) and improving them further would be a big help.

@LawnGnome looking for your input on the value of this from a provenance perspective and for input from a crates-io team perspective on how much we should push this on the Cargo side vs the crates-io side.

[epage]

btw I'm not a fan of adding a lot of boiletplate for cargo new / cargo init, so lean against a commented out line. If its mentioned in [workspace.package.repository] then cargo new will automatically use that.

It would be tempting to say "default to origin" but if the repo is new (the likely case), origin might not be set. Its most if its a workspace without [workspace.package.repository] that this would help.

[LawnGnome]

I like the idea, but the new repo case is definitely a valid issue here.

100% thinking out loud here, but instead of doing this upon package creation, could we instead have cargo package / cargo publish output a diagnostic if the local repo has one or more remotes and there's no repository field available in the package? We could probably even suggest the line to add if there's a remote called origin. (I don't think I'd want to do anything automatically based on origin anyway, since I've seen people use upstream/origin when working with forks and upstream might be the more appropriate value in some cases, but for a suggestion I think it's fine.)

@LawnGnome looking for your input on the value of this from a provenance perspective and for input from a crates-io team perspective on how much we should push this on the Cargo side vs the crates-io side.

From the crates.io side, the thing I'm planning to propose at this stage would be exposing the rev alongside the repository if we have a .cargo_vcs_info.json in the crate file, along with a positive indication if we can match the crate file content to that repo and rev. Obviously having more uptake of the repository field helps with that!

Beyond that, I don't foresee any crates.io side changes that would make sense here. It feels like any new behaviour here to encourage repository use is going to be better implemented in cargo, since it's both closer to the user and has the local environment available to see if there are remotes.

[epage]

Beyond that, I don't foresee any crates.io side changes that would make sense here. It feels like any new behaviour here to encourage repository use is going to be better implemented in cargo, since it's both closer to the user and has the local environment available to see if there are remotes.

The one idea I had was requiring the repository field though I left things open in case other ideas could come up. Likely there are reasons not to but figured it would be worth at least considering.

[LawnGnome]

The one idea I had was requiring the repository field though I left things open in case other ideas could come up. Likely there are reasons not to but figured it would be worth at least considering.

I think that's more prescriptive than we really want to be on the package registry, honestly: if a crate maintainer doesn't use a VCS in general, or Git in particular, that's really their business and not ours. I don't think we'd want to prevent someone from publishing just because of that.

[szabgab]

If I am not mistaken there is no requirement in crates.io for a crate to be open source. In that case most likely it won't have public VCS either. Crates.io probably should warn about this, but if this is to be allowed then the repository field can't be a required field.

[weihanglo]

If I am not mistaken there is no requirement in crates.io for a crate to be open source.

To be precise, crates on crates.io are all distributed as source code ¹. They are free to distribute under any license, not limited to OSI-approved open source license. Besides, having a public accessible VCS is not necessarily a requirement of being “open source”.

Footnotes

1. If they chose to download binaries in build script, that is another story… ↩