diff --git a/guides/checking-licence-compliance.md b/guides/checking-licence-compliance.md index bec3428..7a1bde3 100644 --- a/guides/checking-licence-compliance.md +++ b/guides/checking-licence-compliance.md @@ -6,6 +6,11 @@ Use `cd-check-licence-compliance` as a CI gate or local check when you need to assess the project and its dependencies against the configured licence policy without generating SPDX documents. The command writes no files by default. +When `FILE_LICENCE_IDENTIFIER` is one exact SPDX identifier, CDS also checks +that the configured project licence file exists and matches that identifier +before dependency compliance runs. Compound licence expressions skip this +project-file check. + ## Inputs and example Select a language plugin that provides project metadata. Configure @@ -54,5 +59,7 @@ for the limits and report provenance. To generate SPDX tag-value documents as well as reports, use [`cd-generate-spdx`](generating-an-spdx-sbom.md). See [third-party IP reporting](third-party-ip-reporting.md) for more on reviewing -the summaries and [project configuration](reading-project-configuration.md) -for the shared settings. +the summaries, [project configuration](reading-project-configuration.md) +for the shared settings, and +[syncing the project licence file](syncing-project-licence.md) for the +top-level project licence workflow. diff --git a/guides/checking-project-configuration.md b/guides/checking-project-configuration.md new file mode 100644 index 0000000..a4ef027 --- /dev/null +++ b/guides/checking-project-configuration.md @@ -0,0 +1,37 @@ +# Check CDS project configuration + +## Problem and when to use it + +Use `cd-check-project-config` when you want to validate the CDS-specific +`[ProjectConfig]` section in `pyproject.toml` before running other delivery +commands. It is useful when setting up a project, reviewing configuration +changes, or debugging why another CDS command fails early. + +The command checks the configuration keys CDS understands, validates expected +types, verifies some formats such as regexes, URLs and UUIDs, and reuses the +existing validation for licence-assessment policy overrides. + +## Inputs and example + +Run the command in a repository with `pyproject.toml`: + +```bash +cd-check-project-config +``` + +To validate a specific file path instead of the nearest project config: + +```bash +cd-check-project-config --config-file path/to/pyproject.toml +``` + +## Output + +The command prints `Project configuration is valid.` when the configuration +passes validation. It fails if CDS finds unknown `ProjectConfig` keys, invalid +types, malformed values, or invalid licence-assessment policy settings. + +Use it before [`cd-check-licence-compliance`](checking-licence-compliance.md), +[`cd-generate-spdx`](generating-an-spdx-sbom.md) or +[`cd-tag-and-release`](automating-releases.md) when configuration changes are +part of the work. diff --git a/guides/describing-project-licence-obligations.md b/guides/describing-project-licence-obligations.md new file mode 100644 index 0000000..fa176b1 --- /dev/null +++ b/guides/describing-project-licence-obligations.md @@ -0,0 +1,39 @@ +# Describe project licence obligations + +## Problem and when to use it + +Use `cd-describe-licence-obligations` when you want a quick human-readable +summary of the obligations attached to the project's configured licence. + +The command resolves the project licence from `FILE_LICENCE_IDENTIFIER` and +combines data from SPDX.org, choosealicense.com and OSADL to explain the +licence in practical terms. + +This command only covers projects configured with one exact SPDX identifier. It +does not cover compound expressions such as `Apache-2.0 OR MIT`. + +## Inputs and example + +Configure `FILE_LICENCE_IDENTIFIER` in `[ProjectConfig]` and run: + +```bash +cd-describe-licence-obligations +``` + +## Output + +The command prints a text report including: + +- the SPDX identifier and licence name +- OSI approval when available +- choosealicense.com summary information +- permissions, conditions and limitations when available +- OSADL checklist obligations when available + +For proprietary projects, CDS reports that the author must provide the full +licence text and that obligations need manual review against the custom terms. + +Related commands: + +- [`cd-sync-project-licence`](syncing-project-licence.md) +- [`cd-check-licence-compliance`](checking-licence-compliance.md) diff --git a/guides/index.md b/guides/index.md index ef9dd9c..b307562 100644 --- a/guides/index.md +++ b/guides/index.md @@ -14,6 +14,8 @@ the [plugin guides](https://github.com/ARMmbed/continuous-delivery-scripts/tree/ - [Assess dependency licence risks](assessing-dependency-licences.md): Review directional, explainable licence screening and optional project policy overrides. - [Check licence compliance](checking-licence-compliance.md): Gate a project without generating SPDX files; optionally write reports. +- [Sync the project licence file](syncing-project-licence.md): Create or refresh the top-level project licence file from the configured SPDX identifier. +- [Describe project licence obligations](describing-project-licence-obligations.md): Summarise obligations for the configured project licence. - [Generate an SPDX SBOM](generating-an-spdx-sbom.md): Produce project and dependency SPDX tag-value documents. - [Generate a third-party IP / TPIP report](third-party-ip-reporting.md): Review dependency licences and compliance summaries. - [Manage licence headers](licence-header-management.md): Apply copyright and SPDX headers to source files. @@ -29,6 +31,7 @@ the [plugin guides](https://github.com/ARMmbed/continuous-delivery-scripts/tree/ ## Other project checks - [Generate code documentation](generating-code-documentation.md): Build the API reference. +- [Check project configuration](checking-project-configuration.md): Validate CDS `ProjectConfig` values before running other commands. - [Read project configuration](reading-project-configuration.md): Reuse values in scripts and CI. - [Record accepted secret findings](recording-secrets.md): Maintain the detect-secrets baseline. - [Check for new secrets](checking-for-secrets.md): Scan Git-tracked files in CI. diff --git a/guides/syncing-project-licence.md b/guides/syncing-project-licence.md new file mode 100644 index 0000000..b700b1d --- /dev/null +++ b/guides/syncing-project-licence.md @@ -0,0 +1,49 @@ +# Sync the top-level project licence file + +## Problem and when to use it + +Use `cd-sync-project-licence` when a project has one exact SPDX licence +identifier in `FILE_LICENCE_IDENTIFIER` and you want CDS to create or refresh +the repository's top-level licence file from canonical public licence text. + +This is useful when bootstrapping a project, standardising an existing +`LICENSE` file, or correcting drift before a release or compliance check. + +The command only covers projects configured with one exact SPDX identifier. It +does not cover compound expressions such as `MIT OR Apache-2.0`. + +## Inputs and example + +Configure: + +- `FILE_LICENCE_IDENTIFIER` +- `LICENCE_FILE_PATH` (defaults to `LICENSE`) + +Then run: + +```bash +cd-sync-project-licence +``` + +CDS fetches canonical text in this order when needed: + +1. [ScanCode LicenseDB](https://scancode-licensedb.aboutcode.org/) +2. [SPDX.org](https://spdx.org/licenses/) +3. GitHub licences API +4. [choosealicense.com](https://choosealicense.com/) + +## Output + +If the file is missing, CDS creates it. If the file exists but differs from the +canonical text, CDS shows a diff in verbose mode and rewrites it. If the file +already matches, the command reports success without changing it. + +For a proprietary project, CDS cannot fetch canonical text and instead requires +the author to provide the licence file manually. + +Related commands: + +- [`cd-check-licence-compliance`](checking-licence-compliance.md) for strict + project and dependency licence checks +- [`cd-describe-licence-obligations`](describing-project-licence-obligations.md) + for a summary of obligations diff --git a/news/202610142140000000001.doc b/news/202610142140000000001.doc new file mode 100644 index 0000000..8bde7eb --- /dev/null +++ b/news/202610142140000000001.doc @@ -0,0 +1 @@ +:books: Add guides for checking project configuration and for the project licence sync and obligations commands.