]> git.proxmox.com Git - cargo.git/commit - src/doc/src/reference/manifest.md
src/doc/manifest: Pin 'license' to SPDX 2.1 expressions and the 2.4 list
authorW. Trevor King <wking@tremily.us>
Thu, 4 Jan 2018 18:47:16 +0000 (10:47 -0800)
committerW. Trevor King <wking@tremily.us>
Thu, 4 Jan 2018 19:15:13 +0000 (11:15 -0800)
commit7dee65fed35ca8c802cdceb1d2c98c11c93cc96e
treee0314e7d5daca247e14d63af340a84331cdd5b23
parent29fc01becab01d5836eb0bc74dc9028dd6fa4be9
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
src/doc/manifest.md