From 7dee65fed35ca8c802cdceb1d2c98c11c93cc96e Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 4 Jan 2018 10:47:16 -0800 Subject: [PATCH] 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 --- src/doc/book/src/reference/manifest.md | 21 +++++++++++++++++---- src/doc/manifest.md | 21 +++++++++++++++++---- 2 files changed, 34 insertions(+), 8 deletions(-) diff --git a/src/doc/book/src/reference/manifest.md b/src/doc/book/src/reference/manifest.md index e6bf03a2c47..6cdb3943288 100644 --- 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 55a3ae2fca7..ea42fb1fba2 100644 --- 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