Skip to content

Commit 5c87c14

Browse files
epageepage
committed
docs: Declare support level for each crate in our Charter / docs
This is to bring us into conformance with the [Rust crate ownership policy](https://forge.rust-lang.org/policies/crate-ownership.html). Items of note - `cargo-credential-1password` is declared as Experimental as it is intended for the community but I was unsure if we wanted to commit to full support for it. In my mind, the ideal thing to do would be to expatriate this to 1password. - `home` is declared as Internal despite its wide use within the ecosystem. - `cargo-credential` is declared as Intentional as its an API intended for the wider ecosystem and I didn't see a reason to declare it experimental. - `cargo-platform`, `cargo-util-schemas`, and `crates-io` are declared as Intentional as they are both used internally and intended for others to use for logic that integrates with cargo/registries. I wondered about these being Experimental or Internal instead.
1 parent d199f2e commit 5c87c14

File tree

35 files changed

+133
-28
lines changed

35 files changed

+133
-28
lines changed

‎README.md

+7-5
Original file line numberDiff line numberDiff line change
@@ -9,17 +9,19 @@ Cargo downloads your Rust project’s dependencies and compiles your project.
99
[The Cargo Book]: https://doc.rust-lang.org/cargo/
1010
[Cargo Contributor Guide]: https://rust-lang.github.io/cargo/contrib/
1111

12+
> The Cargo binary distributed through with Rust is maintained by the Cargo
13+
> team for use by the wider ecosystem.
14+
> For all other uses of this crate (as a binary or library) this is maintained
15+
> by the Cargo team, primarily for use by Cargo and not intended for external
16+
> use (except as a transitive dependency). This crate may make major changes to
17+
> its APIs.
18+
1219
## Code Status
1320

1421
[![CI](https://github.com/rust-lang/cargo/actions/workflows/main.yml/badge.svg?branch=auto-cargo)](https://github.com/rust-lang/cargo/actions/workflows/main.yml)
1522

1623
Code documentation: <https://doc.rust-lang.org/nightly/nightly-rustc/cargo/>
1724

18-
## Installing Cargo
19-
20-
Cargo is distributed by default with Rust, so if you've got `rustc` installed
21-
locally you probably also have `cargo` installed locally.
22-
2325
## Compiling from Source
2426

2527
### Requirements

‎benches/benchsuite/README.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
> This crate is maintained by the Cargo team, primarily for use by Cargo
2+
> and not intended for external use. This
3+
> crate may make major changes to its APIs or be deprecated without warning.

‎benches/benchsuite/src/lib.rs

+4
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
//! > This crate is maintained by the Cargo team, primarily for use by Cargo
2+
//! > and not intended for external use. This
3+
//! > crate may make major changes to its APIs or be deprecated without warning.
4+
15
#![allow(clippy::disallowed_methods)]
26

37
use cargo::GlobalContext;

‎crates/cargo-platform/README.md

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
> This crate is maintained by the Cargo team for use by the wider
2+
> ecosystem. This crate follows semver compatibility for its APIs.

‎crates/cargo-platform/src/lib.rs

+3
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@
66
//!
77
//! See `examples/matches.rs` for an example of how to match against a `Platform`.
88
//!
9+
//! > This crate is maintained by the Cargo team for use by the wider
10+
//! > ecosystem. This crate follows semver compatibility for its APIs.
11+
//!
912
//! [`Platform`]: enum.Platform.html
1013
1114
use std::fmt;

‎crates/cargo-test-macro/README.md

+3-5
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
WARNING: You might not want to use this outside of Cargo.
2-
3-
* This is designed for testing Cargo itself. Use at your own risk.
4-
* No guarantee on any stability across versions.
5-
* No feature request would be accepted unless proved useful for testing Cargo.
1+
> This crate is maintained by the Cargo team, primarily for use by Cargo
2+
> and not intended for external use. This
3+
> crate may make major changes to its APIs or be deprecated without warning.

‎crates/cargo-test-macro/src/lib.rs

+3-5
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,9 @@
33
//! This is meant to be consumed alongside `cargo-test-support`. See
44
//! <https://rust-lang.github.io/cargo/contrib/> for a guide on writing tests.
55
//!
6-
//! WARNING: You might not want to use this outside of Cargo.
7-
//!
8-
//! * This is designed for testing Cargo itself. Use at your own risk.
9-
//! * No guarantee on any stability across versions.
10-
//! * No feature request would be accepted unless proved useful for testing Cargo.
6+
//! > This crate is maintained by the Cargo team, primarily for use by Cargo
7+
//! > and not intended for external use. This
8+
//! > crate may make major changes to its APIs or be deprecated without warning.
119
1210
use proc_macro::*;
1311
use std::path::Path;

‎crates/cargo-test-support/README.md

+3-5
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
WARNING: You might not want to use this outside of Cargo.
2-
3-
* This is designed for testing Cargo itself. Use at your own risk.
4-
* No guarantee on any stability across versions.
5-
* No feature request would be accepted unless proved useful for testing Cargo.
1+
> This crate is maintained by the Cargo team, primarily for use by Cargo
2+
> and not intended for external use. This
3+
> crate may make major changes to its APIs or be deprecated without warning.

‎crates/cargo-test-support/src/lib.rs

+3-5
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,9 @@
1111
//! targeted at cargo contributors
1212
//! - Updated on each update of the `cargo` submodule in `rust-lang/rust`
1313
//!
14-
//! **WARNING:** You might not want to use this outside of Cargo.
15-
//!
16-
//! * This is designed for testing Cargo itself. Use at your own risk.
17-
//! * No guarantee on any stability across versions.
18-
//! * No feature request would be accepted unless proved useful for testing Cargo.
14+
//! > This crate is maintained by the Cargo team, primarily for use by Cargo
15+
//! > and not intended for external use. This
16+
//! > crate may make major changes to its APIs or be deprecated without warning.
1917
//!
2018
//! # Example
2119
//!

‎crates/cargo-util-schemas/README.md

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
> This crate is maintained by the Cargo team for use by the wider
2+
> ecosystem. This crate follows semver compatibility for its APIs.

‎crates/cargo-util-schemas/src/lib.rs

+3
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@
44
//! parsing command-lines.
55
//! Any logic for getting final semantics from these will likely need other tools to process, like
66
//! `cargo metadata`.
7+
//!
8+
//! > This crate is maintained by the Cargo team for use by the wider
9+
//! > ecosystem. This crate follows semver compatibility for its APIs.
710
811
pub mod core;
912
pub mod manifest;

‎crates/cargo-util/README.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
> This crate is maintained by the Cargo team, primarily for use by Cargo
2+
> and not intended for external use (except as a transitive dependency). This
3+
> crate may make major changes to its APIs or be deprecated without warning.

‎crates/cargo-util/src/lib.rs

+4
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
11
//! Miscellaneous support code used by Cargo.
2+
//!
3+
//! > This crate is maintained by the Cargo team, primarily for use by Cargo
4+
//! > and not intended for external use (except as a transitive dependency). This
5+
//! > crate may make major changes to its APIs or be deprecated without warning.
26
37
#![allow(clippy::disallowed_methods)]
48

‎crates/crates-io/README.md

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
> This crate is maintained by the Cargo team for use by the wider
2+
> ecosystem. This crate follows semver compatibility for its APIs.

‎crates/crates-io/lib.rs

+3
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
//! > This crate is maintained by the Cargo team for use by the wider
2+
//! > ecosystem. This crate follows semver compatibility for its APIs.
3+
14
use std::collections::BTreeMap;
25
use std::fs::File;
36
use std::io::prelude::*;

‎crates/home/README.md

+4
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,10 @@ that Cargo and rustup store their data.
2020

2121
See [rust-lang/rust#43321].
2222

23+
> This crate is maintained by the Cargo team, primarily for use by Cargo and Rustup
24+
> and not intended for external use. This
25+
> crate may make major changes to its APIs or be deprecated without warning.
26+
2327
[rust-lang/rust#43321]: https://github.com/rust-lang/rust/issues/43321
2428

2529
## License

‎crates/home/src/lib.rs

+4
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,10 @@
1616
//!
1717
//! See also this [discussion].
1818
//!
19+
//! > This crate is maintained by the Cargo team, primarily for use by Cargo and Rustup
20+
//! > and not intended for external use. This
21+
//! > crate may make major changes to its APIs or be deprecated without warning.
22+
//!
1923
//! [discussion]: https://github.com/rust-lang/rust/pull/46799#issuecomment-361156935
2024
2125
#![allow(clippy::disallowed_methods)]

‎crates/mdman/README.md

+4
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@
22

33
mdman is a small utility for creating man pages from markdown text files.
44

5+
> This crate is maintained by the Cargo team, primarily for use by Cargo
6+
> and not intended for external use (except as a transitive dependency). This
7+
> crate may make major changes to its APIs or be deprecated without warning.
8+
59
## Usage
610

711
See the [man page](doc/out/mdman.md) generated by this tool.

‎crates/mdman/src/lib.rs

+4
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
11
//! mdman markdown to man converter.
2+
//!
3+
//! > This crate is maintained by the Cargo team, primarily for use by Cargo
4+
//! > and not intended for external use (except as a transitive dependency). This
5+
//! > crate may make major changes to its APIs or be deprecated without warning.
26
37
use anyhow::{bail, Context, Error};
48
use pulldown_cmark::{CowStr, Event, LinkType, Options, Parser, Tag, TagEnd};

‎crates/resolver-tests/README.md

+4
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,10 @@
55
This crate aims to test the resolution of Cargo's resolver. It implements a [SAT solver](https://en.wikipedia.org/wiki/SAT_solver) to compare with resolution of Cargo's resolver.
66
This ensures that Cargo's dependency resolution is proven valid by lowering to [SAT problem](https://en.wikipedia.org/wiki/Boolean_satisfiability_problem).
77

8+
> This crate is maintained by the Cargo team, primarily for use by Cargo
9+
> and not intended for external use (except as a transitive dependency). This
10+
> crate may make major changes to its APIs or be deprecated without warning.
11+
812
## About the test
913

1014
The Cargo's resolver is very sensitive to what order it tries to evaluate constraints. This makes it incredibly difficult

‎crates/resolver-tests/src/lib.rs

+4
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
//! > This crate is maintained by the Cargo team, primarily for use by Cargo
2+
//! > and not intended for external use (except as a transitive dependency). This
3+
//! > crate may make major changes to its APIs or be deprecated without warning.
4+
15
#![allow(clippy::print_stderr)]
26

37
use std::cmp::{max, min};

‎crates/rustfix/README.md

+4
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@ This is a low-level library. You pass it the JSON output from `rustc`, and you c
99

1010
If you are looking for the [`cargo fix`] implementation, the core of it is located in [`cargo::ops::fix`].
1111

12+
> This crate is maintained by the Cargo team, primarily for use by Cargo and Rust compiler test suite
13+
> and not intended for external use (except as a transitive dependency). This
14+
> crate may make major changes to its APIs or be deprecated without warning.
15+
1216
[`cargo fix`]: https://doc.rust-lang.org/cargo/commands/cargo-fix.html
1317
[`cargo::ops::fix`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/fix.rs
1418

‎crates/rustfix/src/lib.rs

+4
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,10 @@
1818
//! 3. Create a [`CodeFix`] with the source of a file to modify.
1919
//! 4. Call [`CodeFix::apply`] to apply a change.
2020
//! 5. Call [`CodeFix::finish`] to get the result and write it back to disk.
21+
//!
22+
//! > This crate is maintained by the Cargo team, primarily for use by Cargo and Rust compiler test suite
23+
//! > and not intended for external use (except as a transitive dependency). This
24+
//! > crate may make major changes to its APIs or be deprecated without warning.
2125
2226
use std::collections::HashSet;
2327
use std::ops::Range;

‎credential/cargo-credential-1password/README.md

+5
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@
22

33
A Cargo [credential provider] for [1password].
44

5+
> This crate is maintained by the Cargo team as a part of an experiment around
6+
> 1password integration. We encourage people to try to use this crate in their projects and
7+
> provide feedback through [issues](https://github.com/rust-lang/cargo/issues/), but do not
8+
> guarantee long term maintenance.
9+
510
## Usage
611

712
`cargo-credential-1password` uses the 1password `op` CLI to store the token. You

‎credential/cargo-credential-1password/src/main.rs

+5
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
11
//! Cargo registry 1password credential process.
2+
//!
3+
//! > This crate is maintained by the Cargo team as a part of an experiment around
4+
//! > 1password integration. We encourage people to try to use this crate in their projects and
5+
//! > provide feedback through [issues](https://github.com/rust-lang/cargo/issues/), but do not
6+
//! > guarantee long term maintenance.
27
38
#![allow(clippy::disallowed_methods)]
49
#![allow(clippy::print_stderr)]

‎credential/cargo-credential-libsecret/README.md

+4
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,9 @@ See the [credential-provider] documentation for how to use this.
55

66
This credential provider is built-in to cargo as `cargo:libsecret`.
77

8+
> This crate is maintained by the Cargo team, primarily for use by Cargo
9+
> and not intended for external use (except as a transitive dependency). This
10+
> crate may make major changes to its APIs or be deprecated without warning.
11+
812
[GNOME libsecret]: https://wiki.gnome.org/Projects/Libsecret
913
[credential-provider]: https://doc.rust-lang.org/nightly/cargo/reference/registry-authentication.html

‎credential/cargo-credential-libsecret/src/lib.rs

+4
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
//! > This crate is maintained by the Cargo team, primarily for use by Cargo
2+
//! > and not intended for external use (except as a transitive dependency). This
3+
//! > crate may make major changes to its APIs or be deprecated without warning.
4+
15
#[cfg(target_os = "linux")]
26
mod linux {
37
//! Implementation of the libsecret credential helper.

‎credential/cargo-credential-macos-keychain/README.md

+4
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,10 @@ See the [credential-provider] documentation for how to use this.
55

66
This credential provider is built-in to cargo as `cargo:macos-keychain`.
77

8+
> This crate is maintained by the Cargo team, primarily for use by Cargo
9+
> and not intended for external use (except as a transitive dependency). This
10+
> crate may make major changes to its APIs or be deprecated without warning.
11+
812
[macOS Keychain]: https://support.apple.com/guide/keychain-access/welcome/mac
913
[credential-provider]: https://doc.rust-lang.org/nightly/cargo/reference/registry-authentication.html
1014

‎credential/cargo-credential-macos-keychain/src/lib.rs

+4
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
11
//! Cargo registry macos keychain credential process.
2+
//!
3+
//! > This crate is maintained by the Cargo team, primarily for use by Cargo
4+
//! > and not intended for external use (except as a transitive dependency). This
5+
//! > crate may make major changes to its APIs or be deprecated without warning.
26
37
#![allow(clippy::print_stderr)]
48

‎credential/cargo-credential-wincred/README.md

+4
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,9 @@ See the [credential-provider] documentation for how to use this.
55

66
This credential provider is built-in to cargo as `cargo:wincred`.
77

8+
> This crate is maintained by the Cargo team, primarily for use by Cargo
9+
> and not intended for external use (except as a transitive dependency). This
10+
> crate may make major changes to its APIs or be deprecated without warning.
11+
812
[Windows Credential Manager]: https://support.microsoft.com/en-us/windows/accessing-credential-manager-1b5c916a-6a16-889f-8581-fc16e8165ac0
913
[credential-provider]: https://doc.rust-lang.org/nightly/cargo/reference/registry-authentication.html

‎credential/cargo-credential-wincred/src/lib.rs

+4
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
11
//! Cargo registry windows credential process.
2+
//!
3+
//! > This crate is maintained by the Cargo team, primarily for use by Cargo
4+
//! > and not intended for external use (except as a transitive dependency). This
5+
//! > crate may make major changes to its APIs or be deprecated without warning.
26
37
#[cfg(windows)]
48
mod win {

‎credential/cargo-credential/README.md

+3
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,9 @@ https://doc.rust-lang.org/nightly/cargo/reference/credential-provider-protocol.h
1010
Example implementations may be found at
1111
https://github.com/rust-lang/cargo/tree/master/credential
1212

13+
> This crate is maintained by the Cargo team for use by the wider
14+
> ecosystem. This crate follows semver compatibility for its APIs.
15+
1316
## Usage
1417

1518
Create a Cargo project with this as a dependency:

‎credential/cargo-credential/src/lib.rs

+3
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@
1212
//! While in the `perform` function, stdin and stdout will be re-attached to the
1313
//! active console. This allows credential providers to be interactive if necessary.
1414
//!
15+
//! > This crate is maintained by the Cargo team for use by the wider
16+
//! > ecosystem. This crate follows semver compatibility for its APIs.
17+
//!
1518
//! ## Error handling
1619
//! ### [`Error::UrlNotSupported`]
1720
//! A credential provider may only support some registry URLs. If this is the case

‎src/cargo/lib.rs

+4-3
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,10 @@
77
//! - <https://doc.rust-lang.org/nightly/nightly-rustc/cargo>: targeted at cargo contributors
88
//! - Updated on each update of the `cargo` submodule in `rust-lang/rust`
99
//!
10-
//! **WARNING:** Using Cargo as a library has drawbacks, particularly the API is unstable,
11-
//! and there is no clear path to stabilize it soon at the time of writing. See [The Cargo Book:
12-
//! External tools] for more on this topic.
10+
//! > This library is maintained by the Cargo team, primarily for use by Cargo
11+
//! > and not intended for external use (except as a transitive dependency). This
12+
//! > crate may make major changes to its APIs. See [The Cargo Book:
13+
//! > External tools] for more on this topic.
1314
//!
1415
//! ## Overview
1516
//!

‎src/doc/contrib/src/team.md

+9
Original file line numberDiff line numberDiff line change
@@ -166,6 +166,15 @@ The degree of process is correlated with the degree of change being proposed:
166166
[Stable backports]: process/release.md#stable-backports
167167
[SemVer chapter]: https://doc.rust-lang.org/cargo/reference/semver.html
168168

169+
## Intentional Artifacts
170+
171+
Per the [Rust crate ownership policy](https://forge.rust-lang.org/policies/crate-ownership.html), the Cargo team's "Intentional Artifacts" include:
172+
173+
- [cargo-credential](https://crates.io/crates/cargo-credential)
174+
- [cargo-platform](https://crates.io/crates/cargo-platform)
175+
- [cargo-util-schemas](https://crates.io/crates/cargo-util-schemas)
176+
- [crates-io](https://crates.io/crates/crates-io)
177+
169178
## Contacting the team
170179

171180
The team may be contacted through several channels:

0 commit comments

Comments
 (0)