Revision as of 13:06, 19 May 2015

This is a place holder for working on the Best Practices document.

Best Practices

Introduction

Interpreting the Specification

Clarify and help with what is in the spec. Structure sections around the spec?

Tools

Best practices around using the SPDX tools

Contributing to SPDX

how to provide feedback, get involved, etc

Producing

SPDX Version: 1.2 PURPOSE: The SPDX specification is meant to stand on its own and to make clear how a field is to be populated. Still, there are times when more clarification is required. This tech note provides clarification with regard to certain fields about which questions of arisen. Some of these clarifications may be rolled into future versions of the specification.

Package Name (4.1)

The package name should be exclusive of version number. Field 4.2 Package Version is intended for version number and the package name should not redundantly specify this information.

Example

Correct

Package Name: glibc

Package Version: 2.11.1

Incorrect

Package Name: glibc 2.11.1

Package Version: 2.11.1

Package Supplier (4.4); Package Originator (4.5); Source Information (4.10)

The first two fields are intended to where the package came from and what entity created it. In many cases these will be one in the same, but it is possible that the supplier may have gotten the package from another source.

Example:

Wind River supplies the Linux kernel.

Package Supplier: Wind River

Package Originator: linux.org

Source Information is a freeform field, which, like many such fields in SPDX is there to allow the document creator to provide information they feel would be useful or important, but which my not fit neatly into the specification.

Package Download Location (4.6)

The intent of this field is to indicate the URL of the location from which the package is actually obtained. Generally this should be the originating site of the package, but in cases where the package was obtained from a mirror site, the URL of the mirror should be used. The format for the URL should follow RFC conventions, specifically RFC3986 or any newer one that may eventually augment or obsolete it.

Concluded License (4.11); Declared License (4.13)

In cases where there is a contradiction between the Declared License and some other license present, the concluded license should represent that contradiction, and best practice would be to explain further in the 4.14 Comments on License field.

LEGAL TEAM SHOULD REVIEW THIS

Example:

A GPL 2 package that contains files licensed under Apache 2.0.

Declared License: GPL-2.0

Concluded License: GPL-2.0 and Apache-2.0

Comments on License: Several Apache licensed files (A, B, and C) are included in the packages causing an incompatibility with the licensing of the package.

Extracted Text (5.2)

To clarify, or reinforce, the text included here, should be the exact text in that is included with the package and no more. Some early SPDX tools included full text of the relevant license even though the full text was not supplied in the actual package. The example in the specification is one where full text is included, but if the text is incomplete, so should be the text in the Extracted Text field.

Example:

A copying file in the top level of the directory says, “This software is licensed under the Beer License.”

Correct:

Extracted Text: This software is licensed under the Beer-ware License

Incorrect:

“THE BEER-WARE LICENSE" (Revision 42):<phk@FreeBSD.ORG> wrote this file. As long as you retain this notice you can do whatever you want with this stuff. If we meet some day, and you think this stuff is worth it, you can buy me a beer in return Poul-Henning Kam

File Name (6.1)

To clarify, the format for the file name should follow URI RFC conventions, specifically RFC3986 or any newer one that may eventually augment or obsolete it. Specifically, it uses the relative path reference format of an URI, and is defined as being relative to the root of the package from which the file came.

In RFC3986, section 4.2, a relative path reference must not start with a slash character ("/"). Relative references also do not need to start with a "./" (dot slash), although there is one format for which the preceding "./" is necessary. In any case, RFC3986 is clear about how to handle dot-segments, and in the case of "./", it is simply removed.

Example:

Correct:

FileName: ./package/foo.c

FileName: package/foo.c

Incorrect:

FileName: /package/foo.c

FileName: //package/foo.c

Note about RFC3986:

This document obsoletes [RFC2396], which merged "Uniform Resource Locators" [RFC1738] and "Relative Uniform Resource Locators" [RFC1808] in order to define a single, generic syntax for all URIs.

Author vs. Creator (3.1) vs. Reviewer (7.1)

Author: The author is used occasionally in the text of the specification and generally refers to the creator(s) of the package. There is no explicit field for the author information other than copyright information and URL, which may or may not reflect the actual original author. In section 2.2.1, there is also a reference to an "SPDX Author"; this actually refers to the SPDX Creator.

Creator: The SPDX Creator is defined in section 3.1 and is used to identify who (or what, in the case of a tool) created the SPDX file.

Reviewer: The SPDX Reviewer is detined in section 7.1 and is used to identify who reviewed the content of the SPDX.

To put things into context, let's consider the following flow:

1. An author creates a package and assigns a license to it, hopefully to each individual file, and also follows all of the best practices and obligations for the chosen or found licenses in the package.
2. An SPDX creator analyzes the content of the package, extracts the pertinent information and assembles the SPDX file, whether manually or using a tool.
3. An SPDX reviewer inspects the work of the SPDX creator, whether manually or using a tool. Consider the reviewer to be anything from another set of eyes, to a recognized reliable entity with some kind of sign-off authority.

The SPDX creator is a mandatory parameter - every file must have its creator. However, not every SPDX file is reviewed.

Use of Parentheses in License Tag Fields

In the RDF object model, licenses can be defined to be nested disjunctive or conjunctive sets in a very flexible manner. However, when using the Tag value format, it is not clear how, if at all, one could use the parentheses to define more complex licensing scenarios. It is not the intention to restrict either one of the formats, hence we view these additional examples as acceptable:

Examples:

Correct

LicenseConcluded: LGPL-2.0

LicenseConcluded: (LGPL-2.0 or LicenseRef-2)

LicenseConcluded: (LGPL-2.0 and (LicenseRef-2 or LicenseRef-3))

LicenseConcluded: ((LicenseRef-2 or (LicenseRef-3 and LicenseRef-4)) and LGPL-2.0)

Incorrect

LicenseConcluded: (LGPL-2.0)

LicenseConcluded: LGPL-2.0 or LicenseRef-2

LicenseConcluded: (LGPL-2.0 and LicenseRef-2 or LicenseRef-3)

Conceptually, much like in the RDF format, there are no limits to the depth of nested license sets, although practically, more than 2 levels are improbable.

This applies to all license fields.

Consuming

Best practices around the process of doing it. Examples of how this is done.

Notes from LinuxCon 2013 17 Sept 2013

What should be in a best practices, how does it relate to the spec?

Possibilities:

• examples
• particular questions (sort of like a FAQ)
• Could start with things that are not well defined but end up in the specification
• I need a field for X, its not there, what field could I use?
• best practices around the specification and best practices around contributing to SPDX. Maybe two documents?
• Snapshot best practices document at intervals and post on site. Use wiki for active discussions, new proposals, etc.,.
• Should we have a getting started guide?
• best practices for meta tagging like u-boot did. maybe link it in here but should be separate page. Could possibly include other information for developers supporting spdx and producing spdx friendly code. Look at things like U-boot, Mozilla, etc.,.

Examples

This section contains examples of working with SPDX documents.

Converting 1.2 to 2.0

Jack: Show a SPDX 1.2 and then a version of it using 2.0 and explain how one would convert. We can use the spdx tools as the example. Not sure this belongs here. Could be its own thing? May fit better here if there are things you can do when converting that help.

Simple 2.0 Document

Jack: Just a simple use case. Easy to get your head around.

Multiple SPDX Documents in one

Jack: Use this for a test case of multiple documents related to one another and/or multiple documents in one.

OpenSSL Website

External SPDX Documents

Jack: Binary referencing external source spdx documents. We could use SPDX tools here?