Revision as of 17:47, 11 October 2013

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.

4.1 Package Name

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

4.4 Package Supplier; 4.5 Package Originator; 4.10 Source Information

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.

4.6 Package Download Location

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.

4.11 Concluded License; 4.13 Declared License

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.

5.2 Extracted Text

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

6.1 File Name

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.

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.,.