`package.authors` is deprecated without explanation

[GideonBear]

Ref #15068, ping @epage

https://doc.rust-lang.org/cargo/reference/manifest.html#the-authors-field

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. An optional email address may be included within angled brackets at the end of each author entry.
[...]
This field is surfaced in package metadata and in the CARGO_PKG_AUTHORS environment variable within build.rs for backwards compatibility.

I found this in the docs, and had no clue what to do. A warning just saying "This field is deprecated" is not very useful, in my opinion. I was very confused. After a bit of research, I now know why it was deprecated. I propose adding a (short) explanation as to why it was deprecated, possibly a link to the RFC making it optional (which AFAICT contains most of the rationale for deprecating it), and note that you do not need anything to replace it.

Secondly, I think "(deprecated)" should be added in the table of contents:

authors — The authors of the package.

Just like was done with [replace]:

[replace] — Override dependencies (deprecated).

[epage]

For some reason, making too much ado about deprecated functionality in the documentation, like providing treatises explaining why, doesn't sit right with me but unsure if any biases are playing a part in this so I might need to sit on this for a bit.

Specifying what to use instead does make sense but authors was not superseded.

We probably should not link to RFCs. Too many people confuse these as living pieces of documentation, rather than historical documentation. It might work for a deprecation to say "here is the decision" but that is all we can say. Motivations can evolve over time. Even then, the subtlety of where RFCs are relevant can easily be lost.

[GideonBear]

Specifying what to use instead does make sense but authors was not superseded.

With "and note that you do not need anything to replace it", I mean to add a note explicitly saying that it wasn't superseded, and that it's safe to remove it without adding anything else. I expect a deprecation notice to contain something actionable.

The need for an explanation also decreases slightly with that; it's mostly that "this is deprecated" without anything else was very confusing for me.

[epage]

and that it's safe to remove it without adding anything else. I expect a deprecation notice to contain something actionable.

Is it safe to remove? I assume third-party tools, like packagers, are using it and removing it in those contexts is not safe without other steps.

The most we can probably say is that it is ignored by cargo and crates.io

[GideonBear]

Fair point! Lmk what you want to do with it, I can PR.