THE SPDX WIKI IS NO LONGER ACTIVE. ALL CONTENT HAS BEEN MOVED TO https://github.com/spdx
Difference between revisions of "Technical Team/Best Practices"
(→Producing) |
(→5.2 Extracted Text) |
||
Line 63: | Line 63: | ||
: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. | :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 (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. | 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. |
Revision as of 21:28, 15 October 2013
This is a place holder for working on the Best Practices document.
Best Practices
Contents
- 1 Introduction
- 2 Interpreting the Specification
- 3 Tools
- 4 Contributing to SPDX
- 5 Producing
- 6 Consuming
- 7 Notes from LinuxCon 2013 17 Sept 2013
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.
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:
- 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.
- An SPDX creator analyzes the content of the package, extracts the pertinent information and assembles the SPDX file, whether manually or using a tool.
- 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.
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.,.