From af5fd687f19f735fe56c3cb5094878b56a6d9b08 Mon Sep 17 00:00:00 2001
From: Martyn Welch <martyn.welch@collabora.com>
Date: Tue, 6 Jul 2021 16:46:36 +0100
Subject: [PATCH] Rework licensing documentation

The licensing documentation is linked from the home page, but is a bit of a
mess, with guidance on documenting licensing and information about the Apertis
licensing scanning infrastructure mixed with Apertis licensing policies.

Split out the license scanning documentation into a separate architecture
document. Move the small amount of policy documentation from the applying
licensing document and move to guides.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>
---
 content/architecture/license-scanning.md      |  89 ++++++++++
 .../{policies => guides}/license-applying.md  |   6 +
 content/policies/license-exceptions.md        |   9 +-
 content/policies/license-expectations.md      | 153 ++++++------------
 4 files changed, 146 insertions(+), 111 deletions(-)
 create mode 100644 content/architecture/license-scanning.md
 rename content/{policies => guides}/license-applying.md (97%)

diff --git a/content/architecture/license-scanning.md b/content/architecture/license-scanning.md
new file mode 100644
index 000000000..20a638196
--- /dev/null
+++ b/content/architecture/license-scanning.md
@@ -0,0 +1,89 @@
++++
+title = "License Scanning"
+weight = 100
+date = "2021-07-06"
++++
+
+The license is an important element in open source projects as the license 
+define acceptable use cases, user rights, and contribution guidelines. There 
+are different ways to identify the license from the project source code such 
+as SPDX headers, the LICENSE file, and the COPYING file. However an open source 
+project may contain files from other projects and may use different licenses 
+for different files. 
+
+Apertis has certain
+[licensing expectations]({{< ref "license-expectations.md" >}}). In order to
+improve the accuracy of the licensing information, Apertis performs license
+scanning as part of it's continuous integration process
+
+# Ensuring continuous maintenance of open source licence documentation
+
+Maintaining the open source licenses documentation is an incremental process:
+
+When Apertis is rebased on a new version of Debian or new packages are added,
+the licensing is checked for all packages involved.  From a project
+perspective, Apertis teams tries to do a full scan on all projects at each
+release cycle.
+
+During development, updates are monitored. The integration of a new
+project in Apertis and the update of source code are the operations that can
+result in the update of a license. New projects can be integrated at any time
+in Apertis. If new sources for a project already in Apertis are received: the
+licensing of the project can change, or the licensing for some distributables
+within this project can differ from the prevalent license.
+
+Open source software shipped with devices that users buy adds significant
+licensing constraints to the software stack of preview and product releases.
+These constraints do not affect development releases, and it is possible to
+save some work on those releases.
+
+Regular checks of the whole archive have been integrated into Apertis CI
+pipelines to provide early detection of any change to the licensing status of
+each package. A copyright report is generated and kept updated using
+[scan-copyrights]( {{< ref "#scan-copyrights" >}} ), helping
+[Apertis maintainers]({{< ref "contributions.md#the-role-of-maintainers" >}})
+to detect problematic licenses or missing information which may require a
+manual check.
+
+# Source code scanning with scan-copyrights
+
+In order to validate the licensing of a package, the entire package source tree
+needs to be scanned to detect and find copyright holders and known licenses for
+each file. In order to achieve that, the `scan-copyrights` tool has been
+integrated to Apertis CI pipeline, rescanning and updating a copyright report
+for each package on every commit.
+
+Written in Perl, `scan-copyrights` tool from
+[libconfig-model-dpkg-perl](https://salsa.debian.org/perl-team/modules/packages/libconfig-model-dpkg-perl/)
+uses [licensecheck](https://salsa.debian.org/perl-team/modules/packages/licensecheck)
+to parse the source files, detect known licenses and copyright statements,
+outputting the result in plain text or a Debian copyright file format.
+
+Apertis packages keep an exhaustive copyright report in
+`debian/apertis/copyright`, containing information for **every** file in the
+source tree. During this process, missing information and *unacceptable*
+licenses are reported, which may require manual review from developers to
+complete the package copyright report. Two files are used for this purpose:
+
+* `debian/apertis/copyright.yml`: Contains a *mapping* YAML structure, where the
+key is a Perl pattern used to match a path, to manually provide the correct
+copyright information. See
+[Filling_the_blanks](https://manpages.debian.org/buster/libconfig-model-dpkg-perl/Dpkg::Copyright::Scanner.3pm.en.html#Filling_the_blanks).
+
+* `debian/apertis/copyright.whitelist`: Using *git ignore* format, lists files
+that will be ignored if reported with a missing/unacceptable license. Note that
+CI pipeline updates the copyright report with information for **every** file and
+will fail reporting on those problematic entries that weren't whitelisted.
+
+# Future improvements
+
+FOSSology is a license reporting tool. It is being
+[integrated into Apertis]({{< ref "automated-license-compliance.md" >}}) as a
+replacement for `scan-copyrights` as part of an effort to enable end-to-end
+tracking of licensing information. Although [scan-copyrights]( {{< ref
+"#scan-copyrights" >}} ) has helped a lot on automating the process, the
+approach using FOSSology will result in a finer grained and more reliable
+license identification through to the identification of the licensing
+applicable to each binary package.
+
+
diff --git a/content/policies/license-applying.md b/content/guides/license-applying.md
similarity index 97%
rename from content/policies/license-applying.md
rename to content/guides/license-applying.md
index 4fc36f337..32309a448 100644
--- a/content/policies/license-applying.md
+++ b/content/guides/license-applying.md
@@ -13,6 +13,7 @@ aliases = [
 ]
 outputs = [ "html", "pdf-in",]
 date = "2019-10-22"
+lastmod = "2021-07-06"
 +++
 
 Apertis code, including build scripts, helpers and recipes, is primarily
@@ -71,6 +72,11 @@ which would require multiple `COPYING.*` files to be included. This case is
 most common with applications which may include content such as logos, images
 and documentation under different licenses.
 
+{{% notice info %}}
+Apertis performs [license scanning]({{< ref "license-scanning.md" >}}) as part
+of it's continuous integration process to help ensure that the licensing of
+it's packages are correct.
+{{% /notice %}}
 
 #### Distributing portions under different licenses
 
diff --git a/content/policies/license-exceptions.md b/content/policies/license-exceptions.md
index c901d990f..d9960eeeb 100644
--- a/content/policies/license-exceptions.md
+++ b/content/policies/license-exceptions.md
@@ -1,5 +1,5 @@
 +++
-title = "Apertis License exceptions"
+title = "License Exceptions"
 short-description = "Document license exceptions for projects in Apertis"
 weight = 100
 aliases = [
@@ -12,10 +12,9 @@ outputs = [ "html", "pdf-in",]
 date = "2019-04-16"
 +++
 
-# License exceptions
-
-License exceptions for Apertis are listed below.
-Each exception must provide the following informations:
+Exceptions to the Apertis
+[license expectations]({{< ref "license-expectations.md" >}}) are listed below.
+Each exception must provide the following information:
 
 <table>
 <colgroup>
diff --git a/content/policies/license-expectations.md b/content/policies/license-expectations.md
index 9271d49ec..f33e8f332 100644
--- a/content/policies/license-expectations.md
+++ b/content/policies/license-expectations.md
@@ -1,5 +1,5 @@
 +++
-title = "Open Source License Expectations"
+title = "License Expectations"
 short-description = "Document license obligations for projects in Apertis"
 weight = 100
 toc = true
@@ -11,30 +11,22 @@ aliases = [
 ]
 outputs = [ "html", "pdf-in",]
 date = "2019-04-16"
+lastmod = "2021-07-06"
 +++
 
-The license is an important element in open source projects as the license
-define acceptable use cases, user rights, and contribution guidelines. There
-are different ways to identify the license from the project source code such
-as SPDX headers, the LICENSE file, and the COPYING file. However an open source
-project may contain files from other projects and may use different licenses
-for different files.
+Apertis aims to accomplish the following goals with it's licensing:
 
-# Apertis goals
-
-Apertis aims to accomplish the following goals:
-
-- Ensure that all the software shipped in Apertis is open source or at least freely
-distributable, so that downstreams are entitled to
-use, modify and redistribute work derived from our deliverables.
+- Ensure that all the software shipped in Apertis is open source or at least
+  freely distributable, so that downstreams are entitled to use, modify and
+  redistribute work derived from our deliverables.
 - Ensure that Apertis images targeting devices (such as target and minimal),
-are not subject to licensing constraints that may conflict with the regulatory
-requirements of some intended use cases.
+  are not subject to licensing constraints that may conflict with the
+  regulatory requirements of some intended use cases.
 
 In order to reach these goals, the below assumptions are made:
 - **Licenses declared by open source projects are correct:** The software
-  authors correctly document the licensing of their released software sources and
-  that they have all the rights to distribute it under the documented terms.
+  authors correctly document the licensing of their released software sources
+  and that they have all the rights to distribute it under the documented terms.
 - **Licenses verified by the Debian project are correct:** The package
   distributors (that is, Debian maintainers and the FTP Masters team) check that
   the licensing terms provided by the software authors are open source using the
@@ -43,6 +35,12 @@ In order to reach these goals, the below assumptions are made:
   and ensure those terms are documented in a canonical location
   (debian/copyright in the package sources).
 
+{{% notice info %}}
+Apertis also performs [license scanning]({{< ref "license-scanning.md" >}}) as
+part of it's continuous integration process to help ensure that it's licensing
+goals are maintained.
+{{% /notice %}}
+
 # Licensing constraints
 
 Apertis currently limits the usage of the licenses below:
@@ -50,7 +48,6 @@ Apertis currently limits the usage of the licenses below:
 * GPL-3.0 and derivatives (LGPL-3, AGPL-3)
 * BSD-4-Clause
 
-
 ## GPL-3 and derivatives
 
 [Version 3 of the GPL license](https://spdx.org/licenses/GPL-3.0-or-later.html)
@@ -76,68 +73,15 @@ the [BSD-4-Clause-UC](https://spdx.org/licenses/BSD-4-Clause-UC.html) variant
 which resolves the issue on the original software, but not on software with
 different copyright holders.
 
-# Ensuring continuous maintenance of open source licence documentation
-
-Maintaining the open source licenses documentation is an incremental process:
-
-At the time of rebase, licenses are checked for all packages involved in the
-rebase. This covers the whole archive.
-
-During the development, updates are monitored. The integration of a new
-project in Apertis and the update of source code are the operations that can
-result in the update of a license. New projects can be integrated at any time
-in Apertis. If new sources for a project already in Apertis are received: the
-license of the project can change, or the licensing for some distributables
-within this project can differ from the prevalent license.
-
-From a project perspective, Apertis teams tries to do a full scan on all
-projects at each release cycle.
-
-Open source software shipped with devices that users buy adds significant
-licensing constraints to the software stack of preview and product releases.
-These constraints do not affect development releases, and it is possible to
-save some work on those releases.
-
-Regular checks of the whole archive have been integrated into Apertis CI
-pipelines to provide early detection of any change to the licensing status of
-each package. A copyright report is generated and kept updated using
-[scan-copyrights]( {{< ref "#scan-copyrights" >}} ), helping
-[Apertis maintainers]({{< ref "contributions.md#the-role-of-maintainers" >}})
-to detect problematic licenses or missing information which may require manual
-check. [Future improvements]( {{< ref "#future-improvements" >}} ) presents
-an alternative solution.
-
-## scan-copyrights
-
-As a first step, the entire package source tree needs to be scanned to detect
-and find copyright holders and known licenses for each file. In order to achieve
-that, `scan-copyrights` tool has been integrated to Apertis CI pipeline,
-rescanning and updating a copyright report for each package on every release.
-
-Written in Perl, `scan-copyrights` tool from
-[libconfig-model-dpkg-perl](https://salsa.debian.org/perl-team/modules/packages/libconfig-model-dpkg-perl/)
-uses [licensecheck](https://salsa.debian.org/perl-team/modules/packages/licensecheck)
-to parse the source files, detect known licenses and copyright statements,
-outputting the result in plain text or a Debian copyright file format.
-
-Apertis packages keep an exhaustive copyright report in
-`debian/apertis/copyright`, containing information for **every** file in the
-source tree. During this process, missing information and *unacceptable*
-licenses are reported, which may require manual review from developers to
-complete the package copyright report. Two files are used for this purpose:
-
-* `debian/apertis/copyright.yml`: Contains a *mapping* YAML structure, where the
-key is a Perl pattern used to match a path, to manually provide the correct
-copyright information. See
-[Filling_the_blanks](https://manpages.debian.org/buster/libconfig-model-dpkg-perl/Dpkg::Copyright::Scanner.3pm.en.html#Filling_the_blanks).
-
-* `debian/apertis/copyright.whitelist`: Using *git ignore* format, lists files
-that will be ignored if reported with a missing/unacceptable license. Note that
-CI pipeline updates the copyright report with information for **every** file and
-will fail reporting on those problematic entries that weren't whitelisted.
-
 # Apertis Licensing expectations
 
+Code written for Apertis, including build scripts, helpers and recipes, should
+be licensed under the
+[Mozilla Public License Version 2.0](https://www.mozilla.org/en-US/MPL/2.0/).
+Images (such as icons) and documentation in Apertis are licensed under the
+[Creative Commons Attribution-ShareAlike 4.0 International](https://creativecommons.org/licenses/by-sa/4.0/)
+(CC BY-SA 4.0) license.
+
 ## General rules of the Apertis project and their specific constraints
 
 The
@@ -146,8 +90,14 @@ defines expectations for the licenses of the projects that are integrated in
 Debian. They serve as a base for Apertis policy. The DFSG can be read in the
 [Appendix]({{< ref "#appendix" >}}) section of this document.
 
-On top of the DFSG expectations, Apertis defines additional rules for specific sections of its
-package repository which are described in
+{{% notice info %}}
+For more guidance on how to ensure your software properly identifies it's
+licensing, see the guide on
+[applying licensing]({{< ref "license-applying.md" >}}).
+{{% /notice %}}
+
+On top of the DFSG expectations, Apertis defines additional rules for specific
+sections of its package repository which are described in
 [Apertis specific rules]({{< ref "#apertis-repository-component-specific-rules" >}}).
 In particular, the sections in the Apertis package repository are meant
 to group the packages that are installed on images for target devices and
@@ -176,8 +126,8 @@ For current apertis releases, the following components exist:
 - development: contains packages useful for developers
 
 The license expectations for each of those components are defined below.
-Any package outside these expectations should be documented as
-[license exceptions]({{< ref "license-exceptions.md" >}}).
+Any package outside these expectations should be documented as a
+[license exception]({{< ref "license-exceptions.md" >}}).
 
 ### target
 
@@ -242,20 +192,20 @@ DFSG ones.
 
 Auditing the license of an imported package depends of the type of the project.
 
-For debian packages, the Debian licensing informations gives a good indication if a project can be
-integrated in Apertis. Debian maintainers take extreme precaution to ensure that
-what they redistribute is redistributable. Using the Debian licensing
-informations provides many benefits:
+For debian packages, the Debian licensing information gives a good indication
+if a project can be integrated in Apertis. Debian maintainers take extreme
+precaution to ensure that what they redistribute is redistributable. Using the
+Debian licensing information provides many benefits:
 - vetting licensing terms to ensure they are open source (in particular, as
-defined in the DFSG)
+  defined in the DFSG)
 - ensuring that non DFSG-compliant items are excluded from the source code
 - a standardized location for the licensing information (that is,
-`debian/copyright` in the package source)
+  `debian/copyright` in the package source)
 - an ongoing effort to make the provided licensing information machine-readable
-(DEP-5)
+  ([DEP-5](https://dep-team.pages.debian.net/deps/dep5/))
 
 Some projects may not be packaged by Debian. In this case, the project source
-code should contain a document stating the license. Any project that do not
+code should contain a document stating the license. Any project that does not
 provide license information should not be redistributed.
 
 # Documenting exceptions
@@ -275,26 +225,17 @@ The canonical source of Licensing exceptions is the
 Apertis derived projects should provide an equivalent location for their
 specific exceptions.
 
-# Future improvements
-
-FOSSology is a license reporting tool. It is described in the
-[Automated License Compliance]({{< ref "automated-license-compliance.md" >}})
-document along with an approach to enable end-to-end tracking of licensing
-information. Although [scan-copyrights]( {{< ref "#scan-copyrights" >}} ) has
-helped a lot on automating the process, the approach using FOSSology covered in
-the Automated License Compliance concept will result in a finer grained and more
-reliable license identification through to generation of binary packages.
-
 # Appendix
 
 ## The Debian Free Software Guidelines (DFSG)
 
+```
 1. Free Redistribution
 
-The license of a Debian component may not restrict any
-party from selling or giving away the software as a component of an aggregate
-software distribution containing programs from several different sources. The
-license may not require a royalty or other fee for such sale.
+The license of a Debian component may not restrict any party from selling or
+giving away the software as a component of an aggregate software distribution
+containing programs from several different sources. The license may not require
+a royalty or other fee for such sale.
 
 2. Source Code
 
@@ -350,4 +291,4 @@ all other programs distributed on the same medium must be free software.
 
 The "GPL", "BSD", and "Artistic" licenses are examples of licenses that we
 consider "free".
-
+```
-- 
GitLab