On Wed, Apr 11, 2018 at 02:56:38PM -0400, Steve Winslow wrote: > I've been working on a few pages on the SPDX website on why and how > to use SPDX short-form IDs.
This looks good to me :). A few minor nits:
> This is intended to be developer-focused, usable by someone who
> isn't otherwise familiar with SPDX, to get them to start putting
> SPDX identifiers in their source code.
I think that would be clearer if, instead of scoping this as “SPDX
IDs”, you scoped it as “SPDX License Expression Comments” or some
such. That would allign a bit better with the backing appendix [1],
making it clear that this mini-site was about source-comments and not
about associating license expressions in general (which is broader) or
using license list IDs (which is narrower). Along those lines, I wish
the comment tag had been SPDX-License-Expression, but it's too late to
adjust that now ;).
From [2]:
You can replace 20+ lines of license header comments with a single
SPDX-License-Identifier: line.
And later down that same page:
Over time, if you want, you can replace pre-existing complicated
license headers with simple SPDX IDs if your project finds it to be
worthwhile.
The Linux docs make these comments “An alternative to boilerplate
text” [3], and that's how things seem to be working in most of the
kernel. But at least a few files are going with the both/and
approach, e.g. [4]. I'm not sure, but it's possible that the BSD
source redistribution requirement [5], although at least one kernel
file seems to have skipped that [6] (and punted to a LICENSE file that
does not exist in the kernel repo?). You may want to:
* shift the “SPDX IDs are short” entry down after the “SPDX IDs can be
adopted gradually” entry,
* drop the “Over time…” line, and
* add a new line to the “SPDX IDs are short” entry that is something
like:
For license headers that allow it, you can optionally remove
pre-existing license headers after you've added a
SPDX-License-Identifier: line. The MIT and BSD-1-Clause are
examples of license headrs that would not allow this removal.
Further down in [2]:
If your files repeatedly contain multiple lines of all-caps text,
for example, it's possible for changes to the license text to be
introduced -- accidentally or intentionally.
Using SPDX IDs helps reduce the risks of license changes sneaking
into your code.
You may want to replace that with something closer to:
Because they are short, it is easier notice changes—accidental or
intentional—to SPDX license expressions than it is to notice changes
in longer license headers. No more reviewing paragraph re-wrapping
patches to all-caps warrenty disclaimers!
On [7] you have “ARM mbed”, but the upstream casing appears to be “Arm
Mbed” [8]. Also, “Uboot” → “U-Boot” [9], “poco” → “POCO” [10].
On [11], you have an ‘EPL-1.0+’ example, but I think the EPL-1.0
includes that behavior by default [12] and does not provide a way for
licensors to pin to a particular version. Since the -or-later / -only
split, I don't think we have any good examples of a + expression
available. The only other licenses that allow a choice are the CDDL
family, they're or-later by default [13], and we currently do not
provide an ONLY operator or CDDL-1.0-only case, or similar to mark
those pinning notices. I'm not sure what the plans are for the CDDL,
but for the purpose of this mini-site you may just want to ignore the
existence of the + operator, and treat that as covered by the
license-expression appendix link you already have.
The centered entries in the table from [11] caught me out, and I
initially thought the beginning ong the “Apache-2.0 AND (MIT OR
GPL-2.0-only)” explanation was a later paragraph in the “Apache-2.0
AND MIT” explanation. You may want to use a definition list [12] for
this information instead of using a table.
Also on [11], I think you want “how IDs work” → “how license
expressions work”.
You may want to add anchors throughout so folks can link directly to
things like section headers (e.g. the “SPDX License Expressions”
section of [11]).
In the “SPDX License Expressions” section of [11], you make it sound
like the value is a choice between a single license ID or an SPDX
license expressions. But single license IDs are a subset of SPDX
license expressions, via [14]:
license-expression = 1*1(simple-expression / compound-expression)
simple-expression = license-id / license-id”+” / license-ref
I think you could drop that section and use:
3. An SPDX license expression as defined in Appendix IV of the SPDX
specification, version 2.1.
in your “Format” section. In fact, I'd consider dropping all of the
[14] sections after the “Format” section and extending the list of
examples and discussion at the top of [14] to cover the material in
question.
Is there any chance of getting this material into a Git repo? I think
it's harder to track this sort of review via email threads once the
responses exceed 100 lines (like this email ;).
Cheers,
Trevor
[1]:
https://github.com/spdx/spdx-spec/blob/df26160783956ed87d78889dd1d4a53022e713eb/chapters/appendix-V-using-SPDX-short-identifiers-in-source-files.md
[2]: https://spdx.org/ids-why
[3]:
https://www.kernel.org/doc/html/latest/process/license-rules.html#linux-kernel-licensing-rules
[4]:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/arm/boot/dts/bcm953012hr.dts?h=v4.16#n2
[5]:
https://github.com/spdx/license-list-XML/blob/v3.0/src/BSD-3-Clause.xml#L15-L19
[6]:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/staging/greybus/tools/loopback_test.c?h=v4.16#n1
[7]: https://spdx.org/ids-where
[8]: curl -s https://www.mbed.com/en/ | grep -i mbed | head -n1
[9]: https://www.denx.de/wiki/U-Boot/WebHome
[10]: https://pocoproject.org/
[11]: https://spdx.org/ids-how
[12]:
https://github.com/spdx/license-list-XML/blob/v3.0/src/EPL-1.0.xml#L240-L242
[13]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl
[14]: https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60
--
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy
signature.asc
Description: OpenPGP digital signature
_______________________________________________ Spdx-tech mailing list [email protected] https://lists.spdx.org/mailman/listinfo/spdx-tech
