From ea8696bbd8dd9ab5452e744a0465a904742ff718 Mon Sep 17 00:00:00 2001 From: Pietro Albini Date: Thu, 7 Jan 2021 11:44:05 +0100 Subject: [PATCH 1/5] add initial draft of deprecate-authors-field --- text/0000-deprecate-authors-field.md | 128 +++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 text/0000-deprecate-authors-field.md diff --git a/text/0000-deprecate-authors-field.md b/text/0000-deprecate-authors-field.md new file mode 100644 index 00000000000..b076e8e63f0 --- /dev/null +++ b/text/0000-deprecate-authors-field.md @@ -0,0 +1,128 @@ +# RFC: Deprecate the authors field + +- Feature Name: `deprecate_authors_field` +- Start Date: 2021-01-07 +- RFC PR: [rust-lang/rfcs#0000](https://github.com/rust-lang/rfcs/pull/0000) +- Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000) + +# Summary +[summary]: #summary + +This RFC proposes to deprecate the `package.authors` field of `Cargo.toml`. +This also implies preventing Cargo from auto-filling it, allowing crates to be +published to crates.io without the field being present, and avoiding displaying +its contents on the crates.io and docs.rs UI. + +# Motivation +[motivation]: #motivation + +The crates.io registry does not allow users to change the contents of already +published versions: this is highly desirable to ensure working builds don't +break in the future, but it also has the unfortunate side-effect of preventing +people from updating the list of crate authors defined in `Cargo.toml`'s +`package.authors` field. + +This is especially problematic when people change their name or want to remove +their name from the Internet, and the crates.io team doesn't have any way to +address that at the moment except for deleting the affected crates or versions +altogether. We don't do that lightly, but there were a few cases where we were +forced to do so. + +The contents of the field also tend to scale poorly as the size of a project +grows, with projects either making the field useless by just stating "The +$PROJECT developers" or only naming the original authors without mentioning +other major contributors. + +# Guide-level explanation +[guide-level-explanation]: #guide-level-explanation + +crates.io will allow publishing crates without the `package.authors` field, and +it will stop showing the contents of the field in its UI (the current owners +will still be shown). docs.rs will also replace that data with the crate +owners. + +`cargo init` will stop pre-populating the field when running the command, and +it will not include the field at all in the default `Cargo.toml`. Crate authors +will still be able to manually include the field before publishing if they so +choose, even though Cargo will warn when trying to publish those crates. + +# Reference-level explanation +[reference-level-explanation]: #reference-level-explanation + +The implementation of this RFC spans multiple parts of the Rust project: + +## Cargo + +Cargo will stop fetching the current user's name and email address when running +`cargo init`, and it will not include the field in the default template for +`Cargo.toml`. Cargo will also treat the field as deprecated, eventually +displaying a deprecation warning when someone tries to publish a crate with the +field set. + +## crates.io + +crates.io will allow publishing versions without the field and with the field +empty. The Web UI will remove the authors section, while retaining the current +owners section. + +The API will continue returning the `authors` field in every endpoint which +currently includes it, but the field will always be empty (even if the crate +author manually adds data to it). The database dumps will also stop including +the field. + +## docs.rs + +docs.rs will replace the authors with the current owners in its UI. + +# Drawbacks +[drawbacks]: #drawbacks + +Cargo currently provides author information to the crate via +`CARGO_PKG_AUTHORS`, and some crates (such as `clap`) use this information. +Deprecating the authors field will require crates currently using it to change, +such as by inlining the author data. + +This RFC will make it harder for third-party tools to query the author +information of crates published to crates.io. + +By design, this RFC removes the ability to know historical crate authors. In +some cases, crate authors may have wanted that information preserved. After +this RFC, crate authors who want to display historical authors who are not +current crate owners will have to present that information in some other way. + +# Rationale and alternatives +[rationale-and-alternatives]: #rationale-and-alternatives + +This RFC reduces the problems related to changing the names in the authors +field significantly, as people will now have to explicitly want to add that +data instead of it being there by default. + +We could do nothing, but that would increase the support load of the crates.io +team and would result in more crates being removed from the registry due to +this issue. + +# Prior art +[prior-art]: #prior-art + +* **JavaScript:** `package.json` has an optional `authors` field, but it's not + required and the interactive `npm init` command does not prepopulate the + field, leaving it empty by default. The npm Web UI does not show the contents + of the field. +* **Python:** `setup.py` does not require the `authors` field. The PyPI Web UI + shows its contents when present. +* **Ruby:** `*.gemspec` requires the `authors` field, and the RubyGems Web UI + shows its contents. +* **PHP:** `composer.json` has an optional `authors` field. While it's not + required, the interactive `composer init` command allows you to choose + whether to pre-populate it based on the current environment or skip it. The + Packagist Web UI does not show the contents of the field. + +# Unresolved questions +[unresolved-questions]: #unresolved-questions + +* What should we do about the metadata in already published crates? + +# Future possibilities +[future-possibilities]: #future-possibilities + +The `package.authors` field could be removed in a future edition. From e1388a4a9d4c937195a88138f9c566d6c71b835a Mon Sep 17 00:00:00 2001 From: Pietro Albini Date: Fri, 8 Jan 2021 23:36:15 +0100 Subject: [PATCH 2/5] add mutable fields as a future possibility --- text/0000-deprecate-authors-field.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/text/0000-deprecate-authors-field.md b/text/0000-deprecate-authors-field.md index b076e8e63f0..7fee6ddc590 100644 --- a/text/0000-deprecate-authors-field.md +++ b/text/0000-deprecate-authors-field.md @@ -126,3 +126,8 @@ this issue. [future-possibilities]: #future-possibilities The `package.authors` field could be removed in a future edition. + +A future RFC could propose separating metadata fields that could benefit from +being mutable out of `Cargo.toml` and the crate tarball, allowing them to be +changed without having to publish a new version. Such RFC should also propose a +standardized way to update and distribute the extracted metadata. From 6f7c5a0973d12bc2e9760968d938fe0e0612ac2b Mon Sep 17 00:00:00 2001 From: Pietro Albini Date: Sat, 9 Jan 2021 00:04:48 +0100 Subject: [PATCH 3/5] add a note on the changes required to crates --- text/0000-deprecate-authors-field.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/text/0000-deprecate-authors-field.md b/text/0000-deprecate-authors-field.md index 7fee6ddc590..c506656a19a 100644 --- a/text/0000-deprecate-authors-field.md +++ b/text/0000-deprecate-authors-field.md @@ -46,6 +46,13 @@ it will not include the field at all in the default `Cargo.toml`. Crate authors will still be able to manually include the field before publishing if they so choose, even though Cargo will warn when trying to publish those crates. +Crates that currently rely on the field being present (for example by reading +the `CARGO_PKG_AUTHORS` environment variable) will have to handle the field +being missing (for example by switching from the `env!` macro to +`option_env!`). Eventually they will have to provide a way to inline the +information in the crate's source code, if the consumer of the crate desires to +do so. + # Reference-level explanation [reference-level-explanation]: #reference-level-explanation From f8bf22f62f5ffc73700a887c9ba3b6df5621971f Mon Sep 17 00:00:00 2001 From: Pietro Albini Date: Sat, 9 Jan 2021 00:05:53 +0100 Subject: [PATCH 4/5] clarify in the guide-level that the warning will not happen right away This was already clarified in the reference-level section, but it was not reflected in the guide-level explaination. --- text/0000-deprecate-authors-field.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecate-authors-field.md b/text/0000-deprecate-authors-field.md index c506656a19a..586ac132003 100644 --- a/text/0000-deprecate-authors-field.md +++ b/text/0000-deprecate-authors-field.md @@ -44,7 +44,7 @@ owners. `cargo init` will stop pre-populating the field when running the command, and it will not include the field at all in the default `Cargo.toml`. Crate authors will still be able to manually include the field before publishing if they so -choose, even though Cargo will warn when trying to publish those crates. +choose. Eventually Cargo will warn when publishing crates with the field set. Crates that currently rely on the field being present (for example by reading the `CARGO_PKG_AUTHORS` environment variable) will have to handle the field From b023be363655692d14e1cf351331e1c05b825470 Mon Sep 17 00:00:00 2001 From: Pietro Albini Date: Tue, 2 Mar 2021 19:06:07 +0100 Subject: [PATCH 5/5] remove mentions of deprecating the field --- ...ield.md => 0000-optional-authors-field.md} | 38 +++++++++---------- 1 file changed, 18 insertions(+), 20 deletions(-) rename text/{0000-deprecate-authors-field.md => 0000-optional-authors-field.md} (79%) diff --git a/text/0000-deprecate-authors-field.md b/text/0000-optional-authors-field.md similarity index 79% rename from text/0000-deprecate-authors-field.md rename to text/0000-optional-authors-field.md index 586ac132003..7f2773c35ba 100644 --- a/text/0000-deprecate-authors-field.md +++ b/text/0000-optional-authors-field.md @@ -1,6 +1,6 @@ -# RFC: Deprecate the authors field +# RFC: Make the authors field optional -- Feature Name: `deprecate_authors_field` +- Feature Name: `optional_authors_field` - Start Date: 2021-01-07 - RFC PR: [rust-lang/rfcs#0000](https://github.com/rust-lang/rfcs/pull/0000) - Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000) @@ -8,10 +8,10 @@ # Summary [summary]: #summary -This RFC proposes to deprecate the `package.authors` field of `Cargo.toml`. -This also implies preventing Cargo from auto-filling it, allowing crates to be -published to crates.io without the field being present, and avoiding displaying -its contents on the crates.io and docs.rs UI. +This RFC proposes to make the `package.authors` field of `Cargo.toml` optional. +This RFC also proposes preventing Cargo from auto-filling it, allowing crates +to be published to crates.io without the field being present, and avoiding +displaying its contents on the crates.io and docs.rs UI. # Motivation [motivation]: #motivation @@ -44,14 +44,12 @@ owners. `cargo init` will stop pre-populating the field when running the command, and it will not include the field at all in the default `Cargo.toml`. Crate authors will still be able to manually include the field before publishing if they so -choose. Eventually Cargo will warn when publishing crates with the field set. +choose. Crates that currently rely on the field being present (for example by reading the `CARGO_PKG_AUTHORS` environment variable) will have to handle the field being missing (for example by switching from the `env!` macro to -`option_env!`). Eventually they will have to provide a way to inline the -information in the crate's source code, if the consumer of the crate desires to -do so. +`option_env!`). # Reference-level explanation [reference-level-explanation]: #reference-level-explanation @@ -62,9 +60,7 @@ The implementation of this RFC spans multiple parts of the Rust project: Cargo will stop fetching the current user's name and email address when running `cargo init`, and it will not include the field in the default template for -`Cargo.toml`. Cargo will also treat the field as deprecated, eventually -displaying a deprecation warning when someone tries to publish a crate with the -field set. +`Cargo.toml`. ## crates.io @@ -86,16 +82,17 @@ docs.rs will replace the authors with the current owners in its UI. Cargo currently provides author information to the crate via `CARGO_PKG_AUTHORS`, and some crates (such as `clap`) use this information. -Deprecating the authors field will require crates currently using it to change, -such as by inlining the author data. +Making the authors field optional will require crates to account for a missing +field if they want to work out of the box in projects without the field. This RFC will make it harder for third-party tools to query the author information of crates published to crates.io. -By design, this RFC removes the ability to know historical crate authors. In -some cases, crate authors may have wanted that information preserved. After -this RFC, crate authors who want to display historical authors who are not -current crate owners will have to present that information in some other way. +By design, this RFC discourages adding the metadata allowing to know historical +crate authors and makes it harder to retrieve it. In some cases, crate authors +may have wanted that information preserved. After this RFC, crate authors who +want to display historical authors who are not current crate owners will have +to present that information in some other way. # Rationale and alternatives [rationale-and-alternatives]: #rationale-and-alternatives @@ -132,7 +129,8 @@ this issue. # Future possibilities [future-possibilities]: #future-possibilities -The `package.authors` field could be removed in a future edition. +The `package.authors` field could be deprecated and removed in a future +edition. A future RFC could propose separating metadata fields that could benefit from being mutable out of `Cargo.toml` and the crate tarball, allowing them to be