From 35394a2feeb07c984530a53a50d9bc5b02503632 Mon Sep 17 00:00:00 2001 From: Sebastian Schuberth Date: Mon, 30 Oct 2023 18:45:38 +0100 Subject: [PATCH 1/3] docs(RepositoryConfiguration): Improve documentation of two properties Improve the documentation to better explain why both `curations` and `packageConfigurations` have nested `LicenseFindingCuration`s: Their scopes are different (project vs. package). Signed-off-by: Sebastian Schuberth --- model/src/main/kotlin/config/RepositoryConfiguration.kt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/model/src/main/kotlin/config/RepositoryConfiguration.kt b/model/src/main/kotlin/config/RepositoryConfiguration.kt index 56a08dba608c8..85b24d4ab037e 100644 --- a/model/src/main/kotlin/config/RepositoryConfiguration.kt +++ b/model/src/main/kotlin/config/RepositoryConfiguration.kt @@ -52,13 +52,14 @@ data class RepositoryConfiguration( val resolutions: Resolutions = Resolutions(), /** - * Defines curations for artifacts contained in this repository. + * Defines curations for packages used as dependencies by projects in this repository, or curations for license + * findings in the source code of a project in this repository. */ @JsonInclude(value = JsonInclude.Include.CUSTOM, valueFilter = CurationsFilter::class) val curations: Curations = Curations(), /** - * Defines configurations for this repository. + * Defines configurations for packages used as dependencies by projects in this repository. */ @JsonInclude(value = JsonInclude.Include.NON_EMPTY) val packageConfigurations: List = emptyList(), From cdf77cd8bd4d46e95ca9273278bc348d69af984f Mon Sep 17 00:00:00 2001 From: Sebastian Schuberth Date: Fri, 27 Oct 2023 17:02:08 +0200 Subject: [PATCH 2/3] docs(configuration): Improve docs for curations in `.ort.yml` Clearly separate curations from package configurations, like it is done for global ORT configuration, for a better overview. Signed-off-by: Sebastian Schuberth --- website/docs/configuration/ort-yml.md | 182 ++++++++++++++------------ 1 file changed, 100 insertions(+), 82 deletions(-) diff --git a/website/docs/configuration/ort-yml.md b/website/docs/configuration/ort-yml.md index 2e041e32f55d4..00a4a2f5ae7b0 100644 --- a/website/docs/configuration/ort-yml.md +++ b/website/docs/configuration/ort-yml.md @@ -6,8 +6,10 @@ increased degree of automation and local configurations should only be done if t * [excludes](#excludes) - Mark [files, directories](#excluding-paths) or [package manager scopes](#excluding-scopes) as not included in released artifacts. -* [curations](#curations) - Overwrite package metadata, set a concluded license or correct license findings. * [resolutions](#resolutions) - Resolve any issues or policy rule violations. +* [curations](#curations) - Overwrite package metadata, set a concluded license, or correct license findings in the + project. +* [package configurations](#package-configurations) - Define path excludes or correct license findings in dependencies. * [license choices](#license-choices) - Select a license for packages which offer a license choice. The sections below explain each in further detail. Prefer to learn by example? See the @@ -158,87 +160,6 @@ import Yarn from '!!raw-loader!@site/../examples/yarn.ort.yml' {Yarn} ``` -## Curations - -### When to Use Curations - -License finding curations should be used when you want to correct the licenses detected in the source code of the -project. To define curations on global level for third-party packages, please use -[curations](package-curations.md) or [package configurations](package-configurations.md). - -### Curating Project License Findings - -An `ort scan` result represents the detected licenses as a collection of license findings. A single `LicenseFinding` is -represented as a tuple: `(license id, file path, start line, end line)`. Applying a `LicenseFindingCuration` changes the -license-Id of any `LicenseFinding` or eliminates the `LicenseFinding` in case the license is set to `NONE`. - -As an example, the following curation would replace similar findings of `GPL-2.0-only` with `Apache-2.0` in all `.cpp` -files in the `src` directory: - -```yaml -curations: - license_findings: - - path: "src/**/*.cpp" - start_lines: "3" - line_count: 11 - detected_license: "GPL-2.0-only" - reason: "CODE" - comment: "The scanner matches a variable named `gpl`." - concluded_license: "Apache-2.0" - ``` - -To correct identified licenses in a dependency you can use a package configuration to overwrite scanner findings. Note -that this feature requires `enableRepositoryPackageConfigurations` to be enabled in the -[config.yml](../getting-started/usage.md#ort-configuration-file). - -```yaml -package_configurations: -- id: 'Maven:com.example:package:1.2.3' - source_artifact_url: "https://repo.maven.apache.org/maven2/com/example/package/1.2.3/package-1.2.3-sources.jar" - license_finding_curations: - - path: "path/to/problematic/file.java" - start_lines: 22 - line_count: 1 - detected_license: "GPL-2.0-only" - reason: "CODE" - comment: "The scanner matches a variable named `gpl`." - concluded_license: "Apache-2.0" -``` - -For details of the specification, see -[LicenseFindingCuration.kt](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/kotlin/config/LicenseFindingCuration.kt). -The list of available options for `reason` are defined in -[LicenseFindingCurationReason.kt](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/kotlin/config/LicenseFindingCurationReason.kt). - -### Curating Metadata - -Package curations can be added if you want to correct metadata of third-party dependencies. - -The following example corrects the source-artifact URL of the package with the id `Maven:com.example:dummy:0.0.1`. Note -that this feature requires `enableRepositoryPackageCurations` to be enabled in the -[config.yml](../getting-started/usage.md#ort-configuration-file). - -```yaml -curations: - packages: - - id: "Maven:com.example:dummy:0.0.1" - curations: - comment: "An explanation why the curation is needed." - source_artifact: - url: "https://example.com/sources.zip" -``` - -For more information about package curations see -[the documentation for the curations.yml file](package-curations.md). - -### Example - -```mdx-code-block -import Curations from '!!raw-loader!@site/../examples/curations.ort.yml' - -{Curations} -``` - ## Resolutions ### When to Use Resolutions @@ -356,6 +277,103 @@ import Resolutions from '!!raw-loader!@site/../examples/resolutions.ort.yml' {Resolutions} ``` +## Curations + +:::note + +This feature requires `enableRepositoryPackageCurations` to be enabled in the +[config.yml](../getting-started/usage.md#ort-configuration-file). + +::: + +### When to Use Curations + +Similar to global [package curations](package-curations.md), curations can be used to correct metadata of dependencies +specific to the projects in the repository. Additionally, license findings curations may be used to correct the licenses +detected in the source code of the project. To correct license findings detected in dependencies, use global +[package configurations](package-configurations.md) instead. + +### Curating Package Metadata + +The following example corrects the source-artifact URL of the package with the id `Maven:com.example:dummy:0.0.1`: + +```yaml +curations: + packages: + - id: "Maven:com.example:dummy:0.0.1" + curations: + comment: "An explanation why the curation is needed." + source_artifact: + url: "https://example.com/sources.zip" +``` + +### Curating Project License Findings + +An `ort scan` result represents the detected licenses as a collection of license findings. A single `LicenseFinding` is +represented as a tuple: `(license id, file path, start line, end line)`. Applying a `LicenseFindingCuration` changes the +license-Id of any `LicenseFinding` or eliminates the `LicenseFinding` in case the license is set to `NONE`. + +As an example, the following curation would replace similar findings of `GPL-2.0-only` with `Apache-2.0` in all `.cpp` +files in the `src` directory: + +```yaml +curations: + license_findings: + - path: "src/**/*.cpp" + start_lines: "3" + line_count: 11 + detected_license: "GPL-2.0-only" + reason: "CODE" + comment: "The scanner matches a variable named `gpl`." + concluded_license: "Apache-2.0" + ``` + +For details of the specification, see +[LicenseFindingCuration.kt](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/kotlin/config/LicenseFindingCuration.kt). +The list of available options for `reason` are defined in +[LicenseFindingCurationReason.kt](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/kotlin/config/LicenseFindingCurationReason.kt). + +### Full Example + +```mdx-code-block +import Curations from '!!raw-loader!@site/../examples/curations.ort.yml' + +{Curations} +``` + +## Package Configurations + +:::note + +This feature requires `enableRepositoryPackageConfigurations` to be enabled in the +[config.yml](../getting-started/usage.md#ort-configuration-file). + +::: + +### When to Use Package Configurations + +You can use a package configuration to set path excludes or correct detected licenses in a dependency. The following +overwrites a license finding that a scanner found in a source artifact: + +```yaml +package_configurations: +- id: 'Maven:com.example:package:1.2.3' + source_artifact_url: "https://repo.maven.apache.org/maven2/com/example/package/1.2.3/package-1.2.3-sources.jar" + license_finding_curations: + - path: "path/to/problematic/file.java" + start_lines: 22 + line_count: 1 + detected_license: "GPL-2.0-only" + reason: "CODE" + comment: "The scanner matches a variable named `gpl`." + concluded_license: "Apache-2.0" +``` + +For details of the specification, see +[LicenseFindingCuration.kt](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/kotlin/config/LicenseFindingCuration.kt). +The list of available options for `reason` are defined in +[LicenseFindingCurationReason.kt](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/kotlin/config/LicenseFindingCurationReason.kt). + ## License Choices ### When to Use License Choices From 24de18aa400c3ccbe9e4b3ae69bcff72096a25a4 Mon Sep 17 00:00:00 2001 From: Sebastian Schuberth Date: Tue, 31 Oct 2023 10:50:42 +0100 Subject: [PATCH 3/3] chore(markdown-link): Update an ignore pattern to make the linter pass Signed-off-by: Sebastian Schuberth --- mlc_config.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mlc_config.json b/mlc_config.json index cc3241e775327..3e14726244447 100644 --- a/mlc_config.json +++ b/mlc_config.json @@ -16,7 +16,7 @@ "pattern": "^https://source.android.com/setup/develop/repo$" }, { - "pattern": "^../../tutorial/intro$" + "pattern": "^../../tutorial/intro(#.+)?$" } ] }