From 1a18d72993962d1c3ef211acec048e5267f67319 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Wed, 15 Jan 2025 11:08:30 -0600 Subject: [PATCH 1/2] docs(ref): Remove uses of 'package.authors' that isn't documenting something --- src/doc/src/reference/manifest.md | 1 - src/doc/src/reference/workspaces.md | 2 -- 2 files changed, 3 deletions(-) diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md index 5026c9f40a3..ac030e85726 100644 --- a/src/doc/src/reference/manifest.md +++ b/src/doc/src/reference/manifest.md @@ -63,7 +63,6 @@ The first section in a `Cargo.toml` is `[package]`. [package] name = "hello_world" # the name of the package version = "0.1.0" # the current version, obeying semver -authors = ["Alice ", "Bob "] ``` The only field required by Cargo is [`name`](#the-name-field). If publishing to diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index ddbe36fd1ad..4bdbf3b29af 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -54,7 +54,6 @@ where the workspace's `Cargo.toml` is located. [package] name = "hello_world" # the name of the package version = "0.1.0" # the current version, obeying semver -authors = ["Alice ", "Bob "] ``` ### Virtual workspace @@ -77,7 +76,6 @@ resolver = "2" name = "hello_world" # the name of the package version = "0.1.0" # the current version, obeying semver edition = "2024" # the edition, will have no effect on a resolver used in the workspace -authors = ["Alice ", "Bob "] ``` By having a workspace without a root package, From 32d6e9dcfea465a0290321d5559875e1adaa0d49 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Wed, 15 Jan 2025 11:25:34 -0600 Subject: [PATCH 2/2] docs(ref): Deprecate 'package.authors' This was left as a future-possibility in [RFC #3052](https://rust-lang.github.io/rfcs/3052-optional-authors-field.html). Without a clear role for this field within Cargo/crates.io, there seems little reason to actively support it (e.g. #14949, #15027), including working through feature requests. I see the potential for having some fields with more specific roles (where to go for support, where to go for disclosing vulnerabilities, etc) but even these run into the mutable data problem of `authors`. Users can always manage metadata for their own purposes through `package.metadata`. The RFC called out clap as an example of something that uses this. Clap no longer does by default but users can opt-in through a `help_template`. For now, this notes the status in the documentation. When we have[user control over Cargo lint (#12235) (and figure out namespacing with lints that overlap with Rust), we can give a warning on this. Based on feedback from users, we can evaluate removing this field in a future edition. We may want to consider doing similar for `badges` --- src/doc/src/reference/manifest.md | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md index ac030e85726..f23f9f9f7ae 100644 --- a/src/doc/src/reference/manifest.md +++ b/src/doc/src/reference/manifest.md @@ -120,10 +120,10 @@ This field is optional and defaults to `0.0.0`. The field is required for publi ### The `authors` field +> **Warning**: This field is deprecated + The optional `authors` field lists in an array the people or organizations that are considered -the "authors" of the package. The exact meaning is open to interpretation --- it -may list the original or primary authors, current maintainers, or owners of the -package. An optional email address may be included within angled brackets at +the "authors" of the package. An optional email address may be included within angled brackets at the end of each author entry. ```toml @@ -132,13 +132,8 @@ the end of each author entry. authors = ["Graydon Hoare", "Fnu Lnu "] ``` -This field is only surfaced in package metadata and in the `CARGO_PKG_AUTHORS` -environment variable within `build.rs`. It is not displayed in the [crates.io] -user interface. - -> **Warning**: Package manifests cannot be changed once published, so this -> field cannot be changed or removed in already-published versions of a -> package. +This field is surfaced in package metadata and in the `CARGO_PKG_AUTHORS` +environment variable within `build.rs` for backwards compatibility. ### The `edition` field