From 272ef5ba94a4adde86cd0f12d1ff2df16728ed19 Mon Sep 17 00:00:00 2001 From: Jake Shadle Date: Tue, 5 Mar 2024 12:19:25 +0100 Subject: [PATCH] Update docs (#624) Resolves: #622 --- Cargo.lock | 4 +- docs/src/checks/advisories/cfg.md | 28 +++++++++++ docs/src/checks/licenses/cfg.md | 82 ++++++++++++++++++++----------- 3 files changed, 83 insertions(+), 31 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index c70a3016..1dcccf26 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1814,9 +1814,9 @@ dependencies = [ [[package]] name = "mio" -version = "0.8.10" +version = "0.8.11" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8f3d0b296e374a4e6f3c7b0a1f5a51d748a0d34c85e7dc48fc3fa9a87657fe09" +checksum = "a4a650543ca06a924e8b371db273b2756685faae30f8487da1b56505a8f78b0c" dependencies = [ "libc", "wasi", diff --git a/docs/src/checks/advisories/cfg.md b/docs/src/checks/advisories/cfg.md index 09b134e9..5b8e1a7d 100644 --- a/docs/src/checks/advisories/cfg.md +++ b/docs/src/checks/advisories/cfg.md @@ -30,8 +30,28 @@ Note that the path must be valid utf-8, after expansion. Default: `$CARGO_HOME/advisory-dbs` +### The `version` field (optional) + +```ini +version = 2 +``` + +The advisories section has an upcoming breaking change, with deprecation warnings for several fields that will be removed. Setting `version = 2` will opt-in to the future default behavior. + +The breaking change is as follows: + +- `vulnerability` - Removed, all vulnerability advisories now emit errors. +- `unmaintained` - Removed, all unmaintained advisories now emit errors. +- `unsound` - Removed, all unsound advisories now emit errors. +- `notice` - Removed, all notice advisories now emit errors. +- `severity-threshold` - Removed, all vulnerability advisories now emit errors. + +As before, if you want to ignore a specific advisory, add it to the `ignore` field. + ### The `vulnerability` field (optional) +[**DEPRECATED**](#the-version-field-optional) + Determines what happens when a crate with a security vulnerability is encountered. - `deny` (default) - Will emit an error with details about each vulnerability, and fail the check. @@ -40,6 +60,8 @@ Determines what happens when a crate with a security vulnerability is encountere ### The `unmaintained` field (optional) +[**DEPRECATED**](#the-version-field-optional) + Determines what happens when a crate with an `unmaintained` advisory is encountered. - `deny` - Will emit an error with details about the unmaintained advisory, and fail the check. @@ -48,6 +70,8 @@ Determines what happens when a crate with an `unmaintained` advisory is encounte ### The `unsound` field (optional) +[**DEPRECATED**](#the-version-field-optional) + Determines what happens when a crate with an `unsound` advisory is encountered. - `deny` - Will emit an error with details about the unsound advisory, and fail the check. @@ -64,6 +88,8 @@ Determines what happens when a crate with a version that has been yanked from it ### The `notice` field (optional) +[**DEPRECATED**](#the-version-field-optional) + Determines what happens when a crate with a `notice` advisory is encountered. **NOTE**: As of 2019-12-17 there are no `notice` advisories in the [RustSec Advisory DB](https://github.com/RustSec/advisory-db) @@ -89,6 +115,8 @@ In addition, yanked crate versions can be ignored by specifying a [PackageSpec]( ### The `severity-threshold` field (optional) +[**DEPRECATED**](#the-version-field-optional) + The threshold for security vulnerabilities to be turned into notes instead of warnings or errors, depending upon its [CVSS](https://en.wikipedia.org/wiki/Common_Vulnerability_Scoring_System) score. So having a high threshold means some vulnerabilities might not fail the check, but having a log level `>= info` will mean that a note will be printed instead of a warning or error, depending on `[advisories.vulnerability]`. - `None` (default) - CVSS Score 0.0 diff --git a/docs/src/checks/licenses/cfg.md b/docs/src/checks/licenses/cfg.md index d2b02449..49c0de3d 100644 --- a/docs/src/checks/licenses/cfg.md +++ b/docs/src/checks/licenses/cfg.md @@ -45,25 +45,43 @@ allow = [ If `true`, licenses are checked even for `dev-dependencies`. By default this is false as `dev-dependencies` are not used by downstream crates, nor part of binary artifacts. +### The `version` field (optional) + +```ini +version = 2 +``` + +The licenses section has an upcoming breaking change, with deprecation warnings for several fields that will be removed. Setting `version = 2` will opt-in to the future default behavior. + +The breaking change is as follows: + +- `unlicensed` - Removed, if a crate is unlicensed you should open an issue/PR to fix it, and in the meantime, you may add a [clarification](#the-clarify-field-optional). +- `deny` - Removed, all licenses are denied unless explicitly allowed +- `copyleft` - Removed, all licenses are denied unless explicitly allowed +- `allow-osi-fsf-free` - Removed, all licenses are denied unless explicitly allowed +- `default` - Removed, all licenses are denied unless explicitly allowed + ### The `unlicensed` field (optional) Determines what happens when a crate has not explicitly specified its license terms, and no license information could be confidently detected via `LICENSE*` files in the crate's source. -* `deny` (default) - All unlicensed crates will emit an error and fail the license check -* `allow` - All unlicensed crates will show a note, but will not fail the license check -* `warn` - All unlicensed crates will show a warning, but will not fail the license check +- `deny` (default) - All unlicensed crates will emit an error and fail the license check +- `allow` - All unlicensed crates will show a note, but will not fail the license check +- `warn` - All unlicensed crates will show a warning, but will not fail the license check ### The `allow` and `deny` fields (optional) The licenses that should be allowed or denied, note that the same license cannot appear in both the `allow` and `deny` lists. +[`deny` is **DEPRECATED**](#the-version-field-optional) + #### Note on GNU licenses -* GPL -* AGPL -* LGPL -* GFDL +- GPL +- AGPL +- LGPL +- GFDL The GNU licenses are, of course, different from all the other licenses in the SPDX list which makes them annoying to deal with. When supplying one of the above licenses, to either `allow` or `deny`, you **must not** use the suffixes `-only` or `-or-later`, as they can only be used by the license holder themselves to decide under which terms to license their code. @@ -79,12 +97,12 @@ This gets worse with the GFDL licenses, which also have an `invariants` modifier Let's use [`GFDL-1.2`](https://spdx.org/licenses/GFDL-1.2-only.html) to show how license requirements are normalized. -* `GFDL-1.2-invariants-only` => `GFDL-1.2-invariants` -* `GFDL-1.2-invariants-or-later` => `GFDL-1.2-invariants+` -* `GFDL-1.2-no-invariants-only` => `GFDL-1.2` -* `GFDL-1.2-no-invariants-or-later` => `GFDL-1.2+` -* `GFDL-1.2-only` => `GFDL-1.2` -* `GFDL-1.2-or-later` => `GFDL-1.2+` +- `GFDL-1.2-invariants-only` => `GFDL-1.2-invariants` +- `GFDL-1.2-invariants-or-later` => `GFDL-1.2-invariants+` +- `GFDL-1.2-no-invariants-only` => `GFDL-1.2` +- `GFDL-1.2-no-invariants-or-later` => `GFDL-1.2+` +- `GFDL-1.2-only` => `GFDL-1.2` +- `GFDL-1.2-or-later` => `GFDL-1.2+` So, for example, if you wanted to allow all version (1.1, 1.2, and 1.3), but only invariants for 1.3 you could use the following configuration. @@ -134,35 +152,41 @@ exceptions = [ ### The `copyleft` field (optional) +[**DEPRECATED**](#the-version-field-optional) + Determines what happens when a license that is considered [copyleft](https://www.gnu.org/licenses/license-list.html) is encountered. -* `warn` (default) - Will emit a warning that a copyleft license was detected, but will not fail the license check -* `deny` - The license is not accepted if it is copyleft, but the license check might not fail if the expression still evaluates to true -* `allow` - The license is accepted if it is copyleft +- `warn` (default) - Will emit a warning that a copyleft license was detected, but will not fail the license check +- `deny` - The license is not accepted if it is copyleft, but the license check might not fail if the expression still evaluates to true +- `allow` - The license is accepted if it is copyleft ### The `allow-osi-fsf-free` field (optional) +[**DEPRECATED**](#the-version-field-optional) + Determines what happens when licenses aren't explicitly allowed or denied, but **are** marked as [OSI Approved](https://opensource.org/licenses) or [FSF Free/Libre](https://www.gnu.org/licenses/license-list.en.html) in version 3.23 of the [SPDX License List](https://spdx.org/licenses/). -* `both` - The license is accepted if it is both OSI approved and FSF Free -* `either` - The license is accepted if it is either OSI approved or FSF Free -* `osi` - The license is accepted if it is OSI approved -* `fsf` - The license is accepted if it is FSF Free -* `osi-only` - The license is accepted if it is OSI approved and not FSF Free -* `fsf-only` - The license is accepted if it is FSF Free and not OSI approved -* `neither` (default) - No special consideration is given the license +- `both` - The license is accepted if it is both OSI approved and FSF Free +- `either` - The license is accepted if it is either OSI approved or FSF Free +- `osi` - The license is accepted if it is OSI approved +- `fsf` - The license is accepted if it is FSF Free +- `osi-only` - The license is accepted if it is OSI approved and not FSF Free +- `fsf-only` - The license is accepted if it is FSF Free and not OSI approved +- `neither` (default) - No special consideration is given the license ### The `default` field (optional) +[**DEPRECATED**](#the-version-field-optional) + Determines what happens when a license is encountered that: 1. Isn't in the `allow` or `deny` lists 1. Isn't `copyleft` 1. Isn't OSI Approved nor FSF Free/Libre, or `allow-osi-fsf-free = "neither"` -* `warn` - Will emit a warning that the license was detected, but will not fail the license check -* `deny` (default) - The license is not accepted, but the license check might not fail if the expression still evaluates to true -* `allow` - The license is accepted +- `warn` - Will emit a warning that the license was detected, but will not fail the license check +- `deny` (default) - The license is not accepted, but the license check might not fail if the expression still evaluates to true +- `allow` - The license is accepted ### The `confidence-threshold` field (optional) @@ -260,6 +284,6 @@ ignore-sources = ["https://sekretz.com/super/secret-index"] Determines what happens when one of the licenses that appears in the `allow` list is not encountered in the dependency graph. -* `warn` (default) - A warning is emitted for each license that appears in `license.allow` but which is not used in any crate. -* `allow` - Unused licenses in the `licenses.allow` list are ignored. -* `deny` - An unused license in the `licenses.allow` list triggers an error, and cause the license check to fail. +- `warn` (default) - A warning is emitted for each license that appears in `license.allow` but which is not used in any crate. +- `allow` - Unused licenses in the `licenses.allow` list are ignored. +- `deny` - An unused license in the `licenses.allow` list triggers an error, and cause the license check to fail.