Merge pull request #68 from carmenbianca/3.2-improvements

3.2 improvements to documentation
fsfe · Jul 3, 2024 · 164688a · 164688a
2 parents 0043791 + 59a81c9
commit 164688a
Show file tree

Hide file tree

Showing 10 changed files with 785 additions and 587 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -38,45 +38,44 @@ This is the change log for the REUSE Specification.
 ### Security
 -->
 
-## 3.2 - YYYY-MM-DD
+## 3.2 - 2024-07-03
 
 ### Added
 
-- Definition for Commentable and Uncommentable Files. (#123, thanks @Jayman2000)
+- Definition for Commentable and Uncommentable Files. Thanks @Jayman2000.
 - Introduce support of in-line snippet comments using
-  `SPDX-SnippetBegin`/`SPDX-SnippetEnd`. (#107)
-- Specify encoding of `.license` files to UTF-8. (#106, thanks @kirelagin for
-  the helpful background information)
+  `SPDX-SnippetBegin`/`SPDX-SnippetEnd`.
+- Specify encoding of `.license` files to UTF-8. Thanks @kirelagin.
 - Introduce `REUSE-IgnoreStart`/`REUSE-IgnoreEnd` to make the REUSE helper tool
   not consider the enclosed content for detecting copyright and licensing
-  information. (#104)
+  information.
 - Definition for Covered File and clarify for which file copyright and licensing
-  information is required. (#85, thanks @Jayman2000)
-- Remove SPDX documents from list of Covered Files. (#103)
-- Remove symlinks and zero-byte files from list of Covered Files. (#101)
-- Remove submodules and Meson subprojects from list of Covered Files. (#99)
+  information is required. Tanks @Jayman2000.
+- Remove SPDX documents from list of Covered Files.
+- Remove symlinks and zero-byte files from list of Covered Files.
+- Remove submodules and Meson subprojects from list of Covered Files.
 - Clarify which license text files are needed if a SPDX license expression
-  contains more than one license and/or exception. (#96)
-- URLs to currently applicable SPDX specification. (#49)
-- Define an order or precedence. (formerly #131, overhauled in #133)
-- REUSE.toml definition added. (#133)
+  contains more than one license and/or exception.
+- URLs to currently applicable SPDX specification.
+- Define an order or precedence.
+- `REUSE.toml` definition added.
 
 ### Changed
 
 - Allow `.license` files for commentable files, but strongly recommend adding
-  copyright/licensing information in header. (#123, thanks @Jayman2000)
-- Bump referenced SPDX version to 2.3, and update links. (#103) (#107)
+  copyright/licensing information in header. Thanks @Jayman2000.
+- Bump referenced SPDX version to 2.3, and update links.
 
 ### Deprecated
 
-- DEP5 deprecated. (#133)
+- DEP5 deprecated.
 
 ### Fixed
 
 - Minor typos and grammar mistakes. Thanks @jlovejoy and @Jayman2000!
-- Improved definition of Copyright Notices. (#133)
+- Improved definition of Copyright Notices.
 - `COPYING` and `LICENSE` are now marked as ignored, when they were already
-  ignored by the tool since its inception. (#133)
+  ignored by the tool since its inception.
 
 ## 3.1 - 2023-06-21 [YANKED]
 

diff --git a/site/config.toml b/site/config.toml
@@ -7,6 +7,10 @@ languageCode    = "en"
 title           = "REUSE"
 theme           = "github-project-landing-page"
 
+# TODO: Get rid of this. The reason this is here is because a translated page
+# can reference an untranslated page.
+refLinksErrorLevel = "warning"
+
 [markup]
 [markup.tableOfContents]
   endLevel = 3

diff --git a/site/content/en/comparison.md b/site/content/en/comparison.md
@@ -5,12 +5,44 @@
 title: "Comparison of license compliance projects"
 ---
 
-It is easy to get confused by the multitude of initiatives and tools that help with software license compliance. Provided below is a short and incomplete overview of some noteworthy projects.
+It is easy to get confused by the multitude of initiatives and tools that help
+with software license compliance. Provided below is a short and incomplete
+overview of some noteworthy projects.
 
-REUSE does not intend to replace, but rather complement them. We try to solve unclear and missing license and copyright information at the very source. We empower developers to ensure proper and exhaustive licensing of their project.
+REUSE does not intend to replace, but rather complement them. We try to solve
+unclear and missing license and copyright information at the very source. We
+empower developers to ensure proper and exhaustive licensing of their project.
 
-* [**SPDX**](https://spdx.org) is the rock upon which REUSE is built. SPDX defines a standardized way to share copyright and licensing information between projects and people. Read more in [our FAQ](/faq/#what-is-spdx).
-* [**ClearlyDefined**](https://clearlydefined.io) collects and displays meta and security information about a large number of projects distributed on different package registries. It also motivates developers and curators to extend data about a project's licensing and copyright situation. REUSE in comparison concentrates on fixing the problem at the file level for individual projects, which in turn will ease ClearlyDefined's efforts.
-* [**OpenChain**](https://www.openchainproject.org) focuses on making Free Software license compliance more transparent, predictable, and understandable for participants in the software supply chain. OpenChain recommends REUSE as one component to increase clarity of the licensing and copyright situation, but has higher requirements to achieve full conformance.
-* [**FOSSology**](https://www.fossology.org) is a toolkit for Free Software compliance, stores information in a database, and includes license, copyright and export scanners. It is more complex than REUSE and its helper tool and rather optimized for compliance officers and lawyers. REUSE instead intends to have all licensing and copyright information stored in or next to the source files to safeguard this information when reused elsewhere.
-* [**ORT**](https://oss-review-toolkit.org/), the OSS Review Toolkit, is a set of tools that complement existing compliance projects. Its scanner tool runs the license scanner of your choice on the source code of projects and their transitive dependencies. With these being REUSE compliant, it will be much easier for ORT to correctly determine the licenses of all files used in the project.
+- [**SPDX**](https://spdx.org) is the rock upon which REUSE is built. SPDX
+  defines a standardized way to share copyright and licensing information
+  between projects and people. Read more in [our FAQ](/faq/#what-is-spdx).
+- [**ClearlyDefined**](https://clearlydefined.io) collects and displays meta and
+  security information about a large number of projects distributed on different
+  package registries. It also motivates developers and curators to extend data
+  about a project's licensing and copyright situation. REUSE in comparison
+  concentrates on fixing the problem at the file level for individual projects,
+  which in turn will ease ClearlyDefined's efforts.
+- [**OpenChain**](https://www.openchainproject.org) focuses on making Free
+  Software license compliance more transparent, predictable, and understandable
+  for participants in the software supply chain. OpenChain recommends REUSE as
+  one component to increase clarity of the licensing and copyright situation,
+  but has higher requirements to achieve full conformance.
+- [**FOSSology**](https://www.fossology.org) is a toolkit for Free Software
+  compliance. It stores information in a database, and includes license,
+  copyright and export scanners. It is more complex than REUSE and its tool, and
+  rather optimized for compliance officers and lawyers. REUSE instead intends to
+  have all licensing and copyright information stored in or next to the source
+  files to safeguard this information when reused elsewhere. Projects that are
+  REUSE-compliant have their licensing information detected much more easily by
+  FOSSology (specifically its `Ojo` agent).
+- [**ORT**](https://oss-review-toolkit.org/), the OSS Review Toolkit, is a set
+  of tools that complement existing compliance projects. Its scanner tool runs
+  the license scanner of your choice on the source code of projects and their
+  transitive dependencies. If these are REUSE-compliant, it will be much easier
+  for ORT to correctly determine the licenses of all files used in the project.
+- [**AboutCode**](https://aboutcode.org/) is a stack of Software Composition
+  Analysis tools, most pertinently among them the [ScanCode
+  Toolkit](https://github.com/nexB/scancode-toolkit). These tools detect
+  licensing information and generate an inventory of components. Projects that
+  are REUSE-compliant have their licensing information detected much more easily
+  by ScanCode.
diff --git a/site/content/en/dev.md b/site/content/en/dev.md
@@ -11,48 +11,69 @@ Licensing should be easy for developers. We provide several tools and services t
 Contents: [Helper tool](#tool), [example repositories](#repos), [REUSE API](#api), [CI/CD workflows](#ci)
 
 
-## Helper Tool {#tool}
+## REUSE Tool {#tool}
 
-The [REUSE helper tool](https://git.fsfe.org/reuse/tool) assists with achieving and confirming REUSE compliance. It downloads the full license texts, adds copyright and license information to file headers, and contains a linter to identify problems. Eventually, you can generate a software bill of materials.
-
-Read the [documentation](https://reuse.readthedocs.io) to learn more about the tool. You will also find a [tool section in our FAQ](/faq/#tool) for the most pressing questions.
+The [REUSE tool](https://github.com/fsfe/reuse-tool) assists with achieving and
+confirming REUSE compliance. It downloads the full license texts, adds copyright
+and license information to file headers, and contains a linter to identify
+problems. Eventually, you can generate a software bill of materials.
 
+Read the [documentation](https://reuse.readthedocs.io) to learn more about the
+tool. You will also find a ['How do I ...' in our FAQ]({{< relref "faq.md#howto"
+>}}) to learn about various tool interactions.
 
 ## Example repositories {#repos}
 
 What does a REUSE-compliant project look like? The following repositories are basic, but each of them is REUSE-compliant. We make them available to demonstrate how REUSE works in practice.
 
-- [reuse-example](https://git.fsfe.org/reuse/example) - a REUSE compliant repository showing a few methods to add copyright and licensing information. Includes a non-compliant branch for testing. This project is the basis for [our tutorial](/tutorial).
-- [reuse-tool](https://git.fsfe.org/reuse/tool) - the helper tool itself is compliant, just like [all other REUSE repositories](https://git.fsfe.org/reuse/).
-
-Consider registering your project with the [REUSE API](#api) to include a dynamic compliance badge.
+- [reuse-tutorial-example](https://codeberg.org/fsfe/reuse-tutorial-example) - a
+  REUSE-compliant repository that matches the example in [the tutorial]({{<
+  relref "tutorial.md" >}}). Includes a non-compliant branch for testing.
+- [reuse-tool](https://github.com/fsfe/reuse-tool) - the helper tool itself is
+  compliant, just like [all other REUSE
+  repositories](https://git.fsfe.org/reuse/).
 
+Consider registering your project with the [REUSE API](#api) to include a
+dynamic compliance badge.
 
 ## API {#api}
 
-The [REUSE API](https://api.reuse.software) helps you to continuously check and display compliance with the REUSE guidelines. You can include a badge indicating the live status in your README file, and parse the output using the generated JSON file.
+The [REUSE API](https://api.reuse.software) helps you to continuously check and
+display compliance with the REUSE guidelines. You can include a badge indicating
+the live status in your README file, and parse the output using the generated
+JSON file.
 
-This is how the badge will look like for a REUSE compliant project. You can click on the badge to see more information: [![REUSE status](https://api.reuse.software/badge/git.fsfe.org/reuse/api)](https://api.reuse.software/info/git.fsfe.org/reuse/api)
+This is how the badge will look like for a REUSE compliant project. You can
+click on the badge to see more information: [![REUSE
+status](https://api.reuse.software/badge/git.fsfe.org/reuse/api)](https://api.reuse.software/info/git.fsfe.org/reuse/api)
 
-The API is the perfect tool for everyone who wants to show that their repository follows best practices in providing licensing and copyright information. It allows third-party services to integrate the live REUSE status, and offers a simple alternative for people who do not want to install the [REUSE helper tool](#tool) for a first quick check.
-
-As everything else in REUSE, the API is [publicly available](https://git.fsfe.org/reuse/api) under Free Software licenses.
+The API is the perfect tool for everyone who wants to show that their repository
+follows best practices in providing licensing and copyright information. It
+allows third-party services to integrate the live REUSE status, and offers a
+simple alternative for people who do not want to install the [REUSE tool](#tool)
+for a first quick check.
 
+As everything else in REUSE, the API is [publicly
+available](https://git.fsfe.org/reuse/api) under Free Software licenses.
 
 ## Pre-commit hook {#pre-commit-hook}
 
-You can automatically run `reuse lint` on every commit as a pre-commit hook for Git. This uses [pre-commit](https://pre-commit.com/). Once you [have it installed](https://pre-commit.com/#install), add this to the `.pre-commit-config.yaml` in your repository:
+You can automatically run `reuse lint` on every commit as a pre-commit hook for
+Git. This uses [pre-commit](https://pre-commit.com/). Once you [have it
+installed](https://pre-commit.com/#install), add this to the
+`.pre-commit-config.yaml` in your repository:
 
 ```yaml
 repos:
--   repo: https://github.com/fsfe/reuse-tool
-    rev: v1.0.0
+  - repo: https://github.com/fsfe/reuse-tool
+    rev: v4.0.0
     hooks:
-    - id: reuse
+      - id: reuse
 ```
 
-Then run `pre-commit install`. Now, every time you commit, `reuse lint` is run in the background, and will prevent your commit from going through if there was an error.
-
+Then run `pre-commit install`. Now, every time you commit, `reuse lint` is run
+in the background, and will prevent your commit from going through if there was
+an error.
 
 ## Inclusion in CI/CD workflows {#ci}
 
@@ -64,25 +85,45 @@ The FSFE offers a Docker image which can be used in numerous CI solutions. Find
 
 Include the following snippet in your `.drone.yml` file:
 
-```
+```yaml
 steps:
-- name: reuse
-  image: fsfe/reuse:latest
+  - name: reuse
+    image: fsfe/reuse:latest
 ```
 
 More information about Drone on [drone.io](https://drone.io).
 
 ### GitHub
 
-GitHub users can integrate the REUSE action in their workflow. Visit the [action's marketplace page](https://github.com/marketplace/actions/reuse-compliance-check) for usage instructions.
+GitHub users can integrate the REUSE action in their workflow. Include the
+following file as `.github/workflows/reuse.yaml`:
+
+```yaml
+name: REUSE Compliance Check
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: REUSE Compliance Check
+        uses: fsfe/reuse-action@v4
+```
+
+Visit the [action's marketplace
+page](https://github.com/marketplace/actions/reuse-compliance-check) for more
+usage instructions.
 
-More information about GitHub Actions on [help.github.com](https://help.github.com/en/actions/automating-your-workflow-with-github-actions).
+More information about GitHub Actions on
+[docs.github.com](https://docs.github.com/en/actions/).
 
 ### GitLab
 
 Include the following snippet in your `.gitlab-ci.yml` file:
 
-```
+```yaml
 reuse:
   image:
     name: fsfe/reuse:latest
@@ -91,21 +132,22 @@ reuse:
     - reuse lint
 ```
 
-More information about GitLab's CI on [docs.gitlab.com](https://docs.gitlab.com/ce/ci/quick_start/).
+More information about GitLab's CI on
+[docs.gitlab.com](https://docs.gitlab.com/ce/ci/).
 
 ### Travis CI
 
 Include the following snippet in your `.travis.yml` file:
 
-```
+```yaml
 language: minimal
 
 services:
   - docker
 
 before_install:
-- docker pull fsfe/reuse:latest
-- docker run -v ${TRAVIS_BUILD_DIR}:/data fsfe/reuse:latest lint
+  - docker pull fsfe/reuse:latest
+  - docker run -v ${TRAVIS_BUILD_DIR}:/data fsfe/reuse:latest lint
 ```
 
 More information on Travis CI on [travis-ci.com](https://travis-ci.com).