SPDX Wiki - User contributions [en]

Business Team/Adoption

2013-10-17T17:14:26Z

Nglaude: /* Metrics */

DRAFT AS OF 28 August 2013
Currently it is a draft until we formulate the plan at which time this sentence will be removed.

<br />

= Adoption =

This page is being used to track the adoption of SPDX.

We will track adoption in three key areas:
* SPDX License List
* Generating or consuming SPDX Documents
* Using SPDX meta tags in software

<br />

== License List ==

=== Overview ===

The license list is a key component for SPDX. The SPDX License List includes a standardized short identifier, full name for each license, vetted license text, other basic information, and a canonical permanent URL. By providing a short identifier, users can efficiently refer to a license without having to redundantly reproduce the full license. For more information on the License List see the [http://spdx.org/licenses/ SPDX web site].

=== Goals ===

We talked about one year goals. Should we have one and five?

* [proposal] Tool adoption: 5 or more license management / open source tracking tools vendors utilize the SPDX license list
* [proposal] Open Source Projects: 10 or more open source projects visibly utilize the SPDX license list in declaring licenses

=== Metrics ===

For groups use one of the following. You can use multiple groups for an entity.

* Foundation (e.g. Linux Foundation, Free Software, Apache, Eclipse, etc).
* Standards (e.g. OSI, W3C, etc).
* Community (e.g. Community projects like Uboot, Kernel, Busy Box, GNU Compiler, etc).
* Forge (e.g. Github, Sourceforge, etc).
* Tools (e.g. open source community or company that has tools to generate or consume SPDX).
* Company

{| class="wikitable sortable" border="1"
|+ License List Adoption Tracking
! align="left" width=12% | Entity
! width=8% | Group
! class="unsortable" | Notes
|-
| Texas Instruments
| Company
| Using SPDX license identifiers on software BOMs delivered with products.
|-
|-
| Wind River
| Company
| Using SPDX license identifiers in Wind River Linux and we use internally as standard license references.
|-
|-
| Micro Focus
| Company
| Using SPDX license identifiers internally as standard license references. (Tom Incorvia)
|-
|-
| Siemens
| Company
| Using SPDX license identifiers internally as standard license references. (Roger Meier)
|-
|-
| Black Duck
| Tools
| Utilizes license list for references to licenses in Black Duck Suite.
|-
|-
| nexB
| Tools
| Utilizes license list for references to licenses in DejaCode.
|-
|-
| Protecode
| Tools
| Utilizes license list for references to licenses in Protecode Suite.
|-
|-
| FOSSology
| Tools
| Utilizes license list for references to licenses inside tool.
|-
|-
| Open Source Initiative (OSI)
| Standards
| Adopted license list short names.
|-
|}

<br />

== Generation and Consumption of SPDX Documents ==

=== Overview ===
The SPDX specification is centered on the SPDX document. Creation and consumption of SPDX documents is a key measure of success for the SPDX standardization efforts.

=== Goals ===

We talked about one year goals. Should we have one and five?
* Proposal: At least one additional large open source organization provide SPDX documents by LinuxConn 2014

=== Metrics ===

How we will measure adoption of this.
* Proposal: Number of participants in the SPDX document "plugfest".
* Proposal: Number of consuming organizations piloting use of SPDX documents as part of their governance process.
* Proposal: Number of consuming organizations announcing adoption of SPDX as part of their governance process.
* Proposal: Number of producing organizations posting SPDX format documents on the web.
* Proposal: Number of large (more than 100 members) open source organizations producing SPDX documents (e.g. Linux Kernel, Apache, Eclipse).

For groups use one of the following. You can use multiple groups for an entity.

* Foundation (e.g. Linux Foundation, Free Software, Apache, Eclipse, etc).
* Standards (e.g. OSI, W3C, etc).
* Community (e.g. Community projects like Uboot, Kernel, Busy Box, GNU Compiler, etc).
* Forge (e.g. Github, Sourceforge, etc).
* Tools (e.g. open source community or company that has tools to generate or consume SPDX).
* Company

{| class="wikitable sortable" border="1"
|+ SPDX Producer/Consumer Tracking
! align="left" width=12% | Entity
! width=8% | Group
! class="unsortable" | Notes
|-
| Texas Instruments
| Company
| Limited internal generation of SPDX documents.
|-
|-
| Wind River
| Company
| 100% SPDX doc generation - both hi-def (human expert) and low-def (automation); Free SPDX cloud generation: [http://spdx.windriver.com/pkg_upload.aspx]; Format for Open Source disclosure docs for Wind River Linux 5 distro (700+); Used internally in IP compliance review; ISV requested OSS disclosure format; Created website to promote adoption (includes example SPDX files): spdx.windriver.com [http://spdx.windriver.com].
|-
|-
| Alcatel-Lucent
| Company
| Use SPDX documents for internal communication. (Michel Ruffin)
|-
|}

<br/>

== Use of META Tags ==

=== Overview ===

This is a new area. It focuses on using META tags in code to help in identification of licensing and possibly other SPDX information. The technical team is looking at writing this up. Currently the U-boot community has started using a field called SPDX-License-Identifier. You can see an example here:
http://git.denx.de/?p=u-boot.git;a=blob;f=post/post.c;h=4af5355fa5a20f9c2e763f37b269bea38d43e8ea;hb=6612ab33956ae09c5ba2fde9c1540b519625ba37

=== Goals ===

We talked about one year goals. Should we have one and five?
* Proposal: Publish guidelines and/or standards for meta tag inclusion by Linux Collab Summit 2014
* Proposal: 5 or more open source projects utilize meta tags in their in development projects by end of year 2013

=== Metrics ===

For groups use one of the following. You can use multiple groups for an entity.

* Foundation (e.g. Linux Foundation, Free Software, Apache, Eclipse, etc).
* Standards (e.g. OSI, W3C, etc).
* Community (e.g. Community projects like Uboot, Kernel, Busy Box, GNU Compiler, etc).
* Forge (e.g. Github, Sourceforge, etc).
* Tools (e.g. open source community or company that has tools to generate or consume SPDX).
* Company

{| class="wikitable sortable" border="1"
|+ META Tags Tracking
! align="left" width=12% | Entity
! width=8% | Group
! class="unsortable" | Notes
|-
| U-boot
| Community
| [http://git.denx.de/?p=u-boot.git;a=blob;f=post/post.c;h=4af5355fa5a20f9c2e763f37b269bea38d43e8ea;hb=6612ab33956ae09c5ba2fde9c1540b519625ba37]Using SPDX-License-Identifier in place of a license header in source.
|-
|-
| Wind River
| Company
| Wind River developed a file license tagging syntax that uses SPDX License List shortnames.
|-
|}

[[Category:Business]]

Technical Team/Best Practices

2013-10-16T13:28:14Z

Nglaude: /* Use of Parentheses in License Tag Fields */

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

Best Practices

__TOC__

= 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:
# 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.

== 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)

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

Technical Team/Best Practices

2013-10-16T13:28:01Z

Nglaude: /* Use of Parentheses in License Tag Fields */

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

Best Practices

__TOC__

= 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:
# 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.

== 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)

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

Technical Team/Best Practices

2013-10-15T22:08:28Z

Nglaude: /* Use of Parentheses in License Tag Fields */

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

Best Practices

__TOC__

= 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:
# 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.

== 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:

'''Acceptable Examples'''
: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)

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

Technical Team/Best Practices

2013-10-15T22:07:04Z

Nglaude: /* Use of Parentheses in License Tag Fields */

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

Best Practices

__TOC__

= 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:
# 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.

== 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:

'''Acceptable Examples'''
: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)

Conceptually, much like in the RDF format, there are no limits to the depth of nested license sets.

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

Technical Team/Best Practices

2013-10-15T22:06:31Z

Nglaude: /* Use of Parentheses in License Tag Fields */

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

Best Practices

__TOC__

= 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:
# 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.

== 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:

'''Acceptable Examples'''
* 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)

Conceptually, much like in the RDF format, there are no limits to the depth of nested license sets.

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

Technical Team/Best Practices

2013-10-15T21:49:45Z

Nglaude: /* Author vs. Creator (3.1) vs. Reviewer (7.1) */

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

Best Practices

__TOC__

= 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:
# 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.

== Use of Parentheses in License Tag 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.,.

Technical Team/Best Practices

2013-10-15T21:29:37Z

Nglaude: /* 4.1 Package Name */

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

Best Practices

__TOC__

= 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:
# 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.,.

Technical Team/Best Practices

2013-10-15T21:29:22Z

Nglaude: /* 4.4 Package Supplier; 4.5 Package Originator; 4.10 Source Information */

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

Best Practices

__TOC__

= 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

== 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:
# 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.,.

Technical Team/Best Practices

2013-10-15T21:28:48Z

Nglaude: /* 4.6 Package Download Location */

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

Best Practices

__TOC__

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

== 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:
# 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.,.

Technical Team/Best Practices

2013-10-15T21:28:34Z

Nglaude: /* 4.11 Concluded License; 4.13 Declared License */

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

Best Practices

__TOC__

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

== 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:
# 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.,.

Technical Team/Best Practices

2013-10-15T21:28:09Z

Nglaude: /* 5.2 Extracted Text */

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

Best Practices

__TOC__

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

Technical Team/Best Practices

2013-10-15T21:23:45Z

Nglaude: /* Producing */

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

Best Practices

__TOC__

= 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

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

Technical Team/Best Practices

2013-10-11T17:47:37Z

Nglaude: /* Producing */

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

Best Practices

__TOC__

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