Github Rust-lang crate ownership policy by Manishearth · Pull Request #3119 · ru...
source link: https://github.com/rust-lang/rfcs/pull/3119
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
The Rust project publishes a lot of crates, and it's not always clear what their guarantees are. This aims to start an endeavor to categorize these crates and introduce a policy for consistently messaging their raison d'être and guarantees.
This policy doesn't directly affect crates published by the wider ecosystem, however the results of such categorization will likely be very useful to the ecosystem for knowing what should and shouldn't be depended on.
Should we pick categories for all the existing crates as part of the RFC? Or will that be done by individual teams afterwards?
### Internal use
“Internal use” crates should contain the following text near the top of the readme/documentation:
> This crate is maintained by \[team\], primarily for use by \[rust project(s)\] and not intended for external use (except as a transitive dependency). This crate may make major changes to its APIs or be deprecated without warning.
Comment on lines
+64 to +67
jyn514 3 days ago
Member
This is the closest fit for docs.rs and crates.io I think, but the last warning doesn't apply very well to them - they're not libraries, nor will they ever be deprecated. Can the teams have flexibility to change this message a little?
Manishearth 3 days ago
Author
Member
Those are "placeholders" -- if it's not actually a library it's a placeholder; and you should probably not publish the actual code to crates.io. (OTOH conduit is an "internal use" library for crates.io)
But yes, I think we can have flexibility.
jyn514 3 days ago
Member
Oh, I think I misunderstood - this is a policy for crates published to crates.io, not all crates in the rust-lang org. Never mind then.
- **Intentional artifacts**: These are crates which are intentionally released by some team (usually libs), are actively maintained, are intended to be used by external users, and intentionally have an air of officialness. Example: [libc](https://crates.io/crates/libc)
- **Internal use**: These are crates which are used by some “internal client”, like rustc, crates.io, docs.rs, etc. Their primary purpose is not to be used by external users, though the teams that maintain them (typically the teams of their internal client) may wish for the crate to have wider adoption. The line can be blurry between these and “intentional artifacts” and ultimately depends on the goals of the team. Example: [conduit](https://crates.io/crates/conduit), [measureme](https://crates.io/crates/measureme). There are two subcategories based on whether they are intended to ever show up as a transitive dependency:
- **Transitively intentional**: These are dependencies of intentional artifact libraries, and will show up in users' dependency trees, even if they are not intended to be _directly_ used. The Rust Project still needs to handle security issues in these crates _as if_ they are "intentional artifacts".
jyn514 3 days ago
Member
Manishearth 3 days ago
Author
Member
Actually I think that crate is not transitively intentional -- it will never show up in deptrees
jyn514 3 days ago
Member
Hmm, what would you consider a transitively intentional crate then? compiler_builtins is a dependency of core, and will show up if you build core from source with -Zbuild-std.
Manishearth 3 days ago
Author
Member
If a security issue in one of these crates affects a published binary (or crates.io, etc), that will still need to be handled as a bug in the binary or website.
I should mention the stdlib as well.
A transitively intentional crate would be an internal dependency of libc, etc. Basically, it has to show up in your Cargo dependency tree (and as such you need to worry about keeping it up to date).
Manishearth 3 days ago
Author
Member
(I suspect your confusion is stemming from the same place as the other one -- the stdlib is not a published crate, so it is external to this ontology)
Awesome! I love the idea of more intentionally communicating a crate's policy/commitments.
text/0000-rust-crate-ownership.md
Outdated
Any transition to "Intentional Artifact" should ideally be accompanied by an RFC.
Expatriation should basically _never_ occur anymore, but it also requires an RFC and core team approval in case it is really necessary.
BurntSushi 3 days ago
Member
Would it be possible to expand on the strength of wording here? If a team lacks bandwidth to maintain an intentional artifact but some other group of trustworthy people are willing to take it over, then doesn't that require expatriation? Or would y'all expect that the new group become a project team and be brought into the Rust project proper?
(Would it help to perhaps use rand as an example? e.g., If this RFC were active back when rand moved out of rust-lang, how would/should have it been handled instead?)
Manishearth 3 days ago
Author
Member
Would it be possible to expand on the strength of wording here? If a team lacks bandwidth to maintain an intentional artifact but some other group of trustworthy people are willing to take it over, then doesn't that require expatriation? Or would y'all expect that the new group become a project team and be brought into the Rust project proper?
I think that either it becomes a team under our governance or it gets forked; expatriation is an option but I think overall the change of guarantees is pretty major.
BurntSushi 3 days ago
Member
Ah I think I see. It sounds like the fundamental qualification of expatriation is that the same crate name on crates.io is no longer owned by an official Rust group. But it's possible that an "intentional artifact" becomes unmaintained and some other non-official group picks up maintenance, but crucially, with a different crates.io name.
If I have that right, I think it might be worth spelling that out in the RFC text. And I agree, "should basically never happen" sounds about like the right way to handle that case.
aidanhs 3 days ago
Member
Moving to a set of trusted maintainers is still a marked shift from "the Rust Project supports this" in my mind - who defines "trusted"? What happens if they become "less trusted"? I think the "silent swap" is the iffy thing for me, and we can just avoid the issue+questions entirely.
For rand:
- deliberateness around 'intentional artifact' might have prompted a discussion around whether there's real value in 'officialness' and its sustainability long term as a team-supported crate, so it may not have been official in the first place
- if it had been official, I'd see it going via deprecation and a new crate (like rustc_serialize -> serde)
This looks great! I'm wondering what the intent is around crates that have no team or are ambiguous? For example, mdbook does not have a formal team, just a set of maintainers. git2 is used heavily by Cargo, and maybe should be under the cargo team, but that is not clear.
What happens if a team dissolves or fades away? (Presumably some sort of transfer to core or another team and possibly deprecated or expatriated? Would core be responsible for that?)
It might be helpful to have some information on the process of creating and publishing a new crate. The details don't need to be in the RFC, but perhaps the RFC could say that this information will be published on the forge? Right now, the process is roughly: for GitHub: ask infra to create a new repo or accept a transfer of an existing one. For crates.io: publish under a personal account, then invite rust-lang-owner, and hope someone behind that alias accepts the invite (or infra sets up the publishing). This process can be a little ad-hoc and difficult, so it might be nice to make it clearer and easier.
I prefer to keep publishing rights to an absolute minimum instead of allowing the entire team. Is infra willing to create additional GitHub sub-teams for that purpose? How does that work?
I'm wondering what the intent is around crates that have no team or are ambiguous? For example, mdbook does not have a formal team, just a set of maintainers. git2 is used heavily by Cargo, and maybe should be under the cargo team, but that is not clear.
I think an effort can be made to create a team/project group. E.g. I imagine mdbook fitting under devtools.
git2 can just be the cargo team if it's an "internal use", if it's an "intentional artifact" the cargo team can figure it out with the libs team. This RFC does not prescribe a particular choice, it asks the teams to figure it out -- I expect if this lands we will have a slow process of working through the crates and figuring a lot of this out.
The details don't need to be in the RFC, but perhaps the RFC could say that this information will be published on the forge?
Done, it's mostly a matter of process set by the infra team so it's not worth figuring out the details here
I prefer to keep publishing rights to an absolute minimum instead of allowing the entire team. Is infra willing to create additional GitHub sub-teams for that purpose? How does that work?
I think creating a foo-publish team is totally fine. This can again be included in the actual forge page, and doesn't need to be figured out here.
@HeroicKatora and myself been working on a tool that might be of use. It provides visibility into crate ownership for a given crate and all of its dependencies. https://github.com/rust-secure-code/cargo-supply-chain
I've added structured output support (currently in git), so you can create logic for custom policies on top of it. I'd be happy to hear if it works or doesn't work for you. Feature requests are also welcome.
## Transitions and new crates
Teams should feel free to create new crates in any of these categories; however "Intentional Artifact" crates should ideally be accompanied with an RFC. As we move towards having team charters, this will also involve a charter change. Teams should notify [email protected] when they've created such crates so that the core team may track these crates and ensure this policy is applied.
luser 3 days ago
It'd be great to have some guidelines around intentional crates. To me, they seem to occupy a weird niche—important enough for a team to maintain and publish, but not shipped as part of the toolchain itself. When might this be a sensible solution? Should these crates have a long-term plan to become part of core or std?
The thrust of this RFC seems to be to impose some structure upon what was a very ad-hoc process of creating semi-official crates in the rust-lang org. Given that, the other categories make sense to me, but intentional crates still feel odd. What message are they intended to convey to Rust users? "You can trust and rely on these crates, because they are supported by a Rust team just like std"?
If I'm being really honest, crates like libc look like missing bits of core and std. It's pretty hard to write correct FFI without libc, and interop via FFI is a huge selling point of Rust. I'd argue that perhaps we should not be encouraging the creation of new crates like this, but acknowledge the ones that currently exist and are important to the Rust ecosystem while determining a path for them to become part of the distributed toolchain.
Manishearth 3 days ago
Author
Member
I'm actually kinda surprised at this question: the distinction, to me, is pretty straightforward and (I thought) well known: things go in std if we're comfortable permastabilizing them, intentional artifact crates outside of std are ones where we expect to use semver to make changes. Rust tends to default to the latter since permastabilizing an API is a pretty large commitment.
I suggest retitling this to make it more obvious. Something like
Add ownership policy for crates published by the Rust project
The current title sounds like it is talking about every crate.
changed the title Add crate ownership policy
Rust-lang crate ownership policy
Oops, my bad, it picked up the title from the commit
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK