Auto merge of #4898 - wking:license-pin-spdx, r=alexcrichton

src/doc/manifest: Pin 'license' to SPDX 2.1 expressions and the 2.4 list

Before this commit, the license-list URL was floating, which lead to issues when manifest authors used IDs from the list that had not yet made it into crate.io's whitelist (#4888).  This commit pins both the SPDX-spec version (to avoid floating the license-expresion syntax) and the license-list version (to avoid floating the license/exception identifiers).

I've also deprecated the `/` syntax, since it was not clear whether that was conjunctive (like `AND`) or disjunctive (like `OR`).  crates.io is [using license-exprs 1.3^][2], and [that version supports `WITH`, `AND`, `OR`, and the `+` suffix][3], so as far as crates.io-validation is concerned, the value can use vanilla license expressions.

It's unfortunate that there's not an easily-browsable version of the 2.4 license list up anywhere canonical (as far as I know).  Starting with the 3.0 license list, there's [a Markdown page in the authoritative list-data repository][4].  I can also see about getting [earlier versions of the HTML][5] up on spdx.org somewhere.

I'm expecting the version-bump procedure will look something like:

1. SPDX cuts a new spec and/or license list release.
2. license-exprs updates to cover the change.
3. crates.io updates to depend on the new license-exprs version.
4. cargo updates the documentation to allow the new version.
5. authors read the new cargo docs and start using the new expression syntax and/or identifiers.

There's a window there where crates.io will be validating to a different version than the cargo docs recommend, so it would be good to have 4 follow 3 as closely as possible.  But the SPDX maintainers have been good about providing long deprecation windows, so a bit of a gap is acceptable.

It's possible that crates.io will want to warn authors about their use of deprecated identifiers or syntax (e.g. the `/` I've deprecated here) so they can upgrade before the deprecated element is dropped (probably years after the initial deprecation).  That would help limit the gap between 3 and 5 (although warnings sent before 4 might be confusing).

The parallel edits to the two manifest files are based on @carols10cents' recommendation.  She [points out on IRC][6] that the goal is to drop the `src/doc/manifest.md` reference soon with the book up on `doc.rust-lang.org/cargo` today.

Fixes #4888, although it would be good to start the upgrade cycle to pull in the [newly-released SPDX license list 3.0][7] so folks can start using the new identifiers.

[2]: rust-lang/crates.io#385
[3]: https://github.com/withoutboats/license-exprs/blob/5bdb5355540792234e10011b9bbe4766cd08ff26/src/lib.rs#L53-L56
[4]: https://github.com/spdx/license-list-data/blob/v3.0/licenses.md
[5]: https://github.com/spdx/license-list-data/tree/v2.4/website
[6]: https://botbot.me/mozilla/cargo/2018-01-04/?msg=95358280&page=2
[7]: https://lists.spdx.org/pipermail/spdx/2017-December/001159.html

src/doc/book/src/reference/manifest.md

@@ -168,10 +168,14 @@ keywords = ["...", "..."]
 # they must match exactly.
 categories = ["...", "..."]
 
-# This is a string description of the license for this package. Currently
-# crates.io will validate the license provided against a whitelist of known
-# license identifiers from http://spdx.org/licenses/. Multiple licenses can be
-# separated with a `/`.
+# This is an SPDX 2.1 license expression for this package.  Currently
+# crates.io will validate the license provided against a whitelist of
+# known license and exception identifiers from the SPDX license list
+# 2.4.  Parentheses are not currently supported.
+#
+# Multiple licenses can be separated with a `/`, although that usage
+# is deprecated.  Instead, use a license expression with AND and OR
+# operators to get more explicit semantics.
 license = "..."
 
 # If a project is using a nonstandard license, then this key may be specified in
@@ -235,6 +239,11 @@ provide useful information to users of the registry and also influence the
 search ranking of a crate. It is highly discouraged to omit everything in a
 published crate.
 
+SPDX 2.1 license expressions are documented
+[here][spdx-2.1-license-expressions].  The current version of the
+license list is available [here][spdx-license-list], and version 2.4
+is available [here][spdx-license-list-2.4].
+
 #### The `metadata` table (optional)
 
 Cargo by default will warn about unused keys in `Cargo.toml` to assist in
@@ -761,3 +770,7 @@ source (e.g. git or a local path).
 
 More information about overriding dependencies can be found in the [overriding
 dependencies][replace] section of the documentation.
+
+[spdx-2.1-license-expressions]: https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60
+[spdx-license-list]: https://spdx.org/licenses/
+[spdx-license-list-2.4]: https://github.com/spdx/license-list-data/tree/v2.4

src/doc/manifest.md

@@ -165,10 +165,14 @@ keywords = ["...", "..."]
 # they must match exactly.
 categories = ["...", "..."]
 
-# This is a string description of the license for this package. Currently
-# crates.io will validate the license provided against a whitelist of known
-# license identifiers from http://spdx.org/licenses/. Multiple licenses can be
-# separated with a `/`.
+# This is an SPDX 2.1 license expression for this package.  Currently
+# crates.io will validate the license provided against a whitelist of
+# known license and exception identifiers from the SPDX license list
+# 2.4.  Parentheses are not currently supported.
+#
+# Multiple licenses can be separated with a `/`, although that usage
+# is deprecated.  Instead, use a license expression with AND and OR
+# operators to get more explicit semantics.
 license = "..."
 
 # If a project is using a nonstandard license, then this key may be specified in
@@ -234,6 +238,11 @@ provide useful information to users of the registry and also influence the
 search ranking of a crate. It is highly discouraged to omit everything in a
 published crate.
 
+SPDX 2.1 license expressions are documented
+[here][spdx-2.1-license-expressions].  The current version of the
+license list is available [here][spdx-license-list], and version 2.4
+is available [here][spdx-license-list-2.4].
+
 ## The `metadata` table (optional)
 
 Cargo by default will warn about unused keys in `Cargo.toml` to assist in
@@ -795,3 +804,7 @@ source (e.g. git or a local path).
 
 More information about overriding dependencies can be found in the [overriding
 dependencies][replace] section of the documentation.
+
+[spdx-2.1-license-expressions]: https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60
+[spdx-license-list]: https://spdx.org/licenses/
+[spdx-license-list-2.4]: https://github.com/spdx/license-list-data/tree/v2.4