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 [1].  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 (e.g. [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 Carol
Nichols' recommendation.  She points out on IRC that the goal is to
drop the src/doc/manifest.md reference soon with the book up on
doc.rust-lang.org/cargo today [6].

[1]: https://github.com/rust-lang/cargo/issues/4888
[2]: https://github.com/rust-lang/crates.io/pull/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

diff --git a/src/doc/book/src/reference/manifest.md b/src/doc/book/src/reference/manifest.md
index e6bf03a2c472ab8ec0ca7a62a225f4a5dfdeb29e..6cdb394328824c5ce3143b0d5511c7ea48b9bf54 100644 (file)
--- a/src/doc/book/src/reference/manifest.md
+++ b/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.
+#
+# 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

diff --git a/src/doc/manifest.md b/src/doc/manifest.md
index 55a3ae2fca7abdff7e60a02a85d685b9509385ac..ea42fb1fba269293ec482d1c347f5aca7a6e3853 100644 (file)
--- a/src/doc/manifest.md
+++ b/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.
+#
+# 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