From 234d403736e91e85e17f51fe54ca1d697d8037c2 Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Tue, 11 May 2021 15:03:43 +1000 Subject: [PATCH 1/2] adding license proposal --- proposed/2021/LicenseInspection.md | 133 +++++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 proposed/2021/LicenseInspection.md diff --git a/proposed/2021/LicenseInspection.md b/proposed/2021/LicenseInspection.md new file mode 100644 index 0000000000..38d6dd784c --- /dev/null +++ b/proposed/2021/LicenseInspection.md @@ -0,0 +1,133 @@ +# `dotnet nuget license` + +- Author Name [Aaron Powell](https://github.com/aaronpowell) +- Start Date (2021-05-11) +- GitHub Issue N/A +- GitHub PR TBC + +## Summary + +This command will allow someone to inspect all the licenses that are specified for the referenced packages, as well as transient packages, of a project. + +## Motivation + +The motivation is to give people more insights into the licenses that are used in a project, ensuring they can stay compliant with the licenses. + +## Explanation + +### Functional explanation + +On the new project you're building, there are dependencies on NuGet packages from a remote feed, and those packages in turn have their own dependencies. This has resulted in an opaque view of what licenses are being consumed by the project. + +Your companies legal department has outlined a list of open source licenses that it is comfortable consuming and others that it wants to avoid using. + +To avoid accidentally consuming an unsupported license we need a way to view the list and ideally fail builds when we use one of these licenses. + +#### Local scenario + +You have just added a new NuGet dependency into the project and want to ensure it doesn't bring in any unsupported licenses. + +From the command line you run the license command: + +```bash +$> dotnet nuget license +``` + +This outputs a human readable view of the license information: + +``` +Project dotnet-delice +License Expression: MIT +├── There are 10 occurances of MIT +├─┬ Conformance: +│ ├── Is OSI Approved: true +│ ├── Is FSF Free/Libre: true +│ └── Included deprecated IDs: false +└─┬ Packages: + ├── FSharp.Core + ├── Microsoft.NETCore.App + ├── Microsoft.NETCore.DotNetAppHost + ├── Microsoft.NETCore.DotNetHostPolicy + ├── Microsoft.NETCore.DotNetHostResolver + ├── Microsoft.NETCore.Platforms + ├── Microsoft.NETCore.Targets + ├── NETStandard.Library + ├── Newtonsoft.Json + └── System.ComponentModel.Annotations +``` + +Satisfied with the licenses, you continue on with the task at hand. + +#### Blocking builds + +It's time to update our build pipeline to avoid releasing anything changes that introduce unsupported licenses. A new step is added to the pipeline YAML: + +```yml +- name: Validate Licenses + runs: | + LICENSES=$(dotnet nuget license --json | jq '') + if ($LICENSES) then + exit 0 + fi +``` + +This (pseduocode version) will dump the licenses to a JSON structure that can be parsed with a tool such as [jq](https://stedolan.github.io/jq/) and inspected for invalid licenses. If any are found an error code is returned, stopping the build from completing successfully. + +### Technical explanation + +The first technical challenge for this is the inconsistent nature of which licenses are provided by NuGet packages. While the [`licenseUrl` field was deprecated](https://github.com/NuGet/Announcements/issues/32) a large number of packages still haven't adopted the new format, making it difficult to determine what the license of a project is. + +The next challenge is how to detect licenses from license files. The ideal approach would be to mirror GitHub's approach, which uses [Licensee](https://licensee.github.io/licensee/) [for detection](https://help.github.com/en/articles/licensing-a-repository#detecting-a-license) (but naturally a dotnet implementation). Essentially this uses [Sørensen–Dice coefficient](https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient) with a threshold for what is the acceptable level of comparison between the provided license and license template. + +The technical workflow for license detection would follow: + +- If a `license` field is in the nuspec, check if it's a SPDX ID, if so, return. If it's a file, use Sørensen–Dice coefficient to compare it to a known list +- If a `licenseUrl` is provided, attempt to download the license from the endpoint and compare with the known list +- Fallback to looking at the package feed and see if it provides license information + +It may also be worth having the facility to cache the SPDX license information from https://spdx.org/licenses/licenses.json to improve lookup performance + +#### `$> dotnet nuget license [folder, sln, csproj, fsproj] [OPTIONS]` + +##### Commands + +- `-?|-h|--help` Boolean. Show help. +- `-j|--json` Boolean. Output results as JSON rather than pretty-print. +- `--json-output [path]` String. Path to file that the JSON should be written to. Note: Only in use if you use `-j|--json`. +- `--check-github` Boolean. If the license URL (for a legacy package) points to a GitHub hosted file, use the GitHub API to try and retrieve the license type. +- `--github-token ` String. A GitHub Personal Access Token (PAT) to use when checking the GitHub API for license types. This avoids being [rate limited](https://developer.github.com/v3/#rate-limiting) when checking a project. +- `--check-license-content` Boolean. When provided the contents of the license file will be compared to known templates. +- `--refresh-spdx` Boolean. When provided the tool will also refresh the SPDX license cache used for conformance information. + +##### Output + +- Project Name + - The name of the project that was checked +- License Expression + - A license expression found when parsing references + - Some packages may result in an undetermined license +- Packages + - The name(s) of the packages found for that license + +## Drawbacks + +Not having functionality to do this will result in users having to rely on third-party tooling, manually resolving the information themselves or being unaware they may break license restrictions. + +## Rationale and alternatives + +The rationale is to give people as much information as possible about the OSS that they rely on, ensuring they can make the most informed decisions on the dependencies they have and the legal requirements they are to be held to. + +## Prior Art + +I have created a dotnet global tool that does this, [`dotnet-delice`](https://github.com/aaronpowell/dotnet-delice). This does prove that it is a technical possibility to implement such a solution. + +There is a [similar proposal for npm](https://github.com/npm/rfcs/pull/182), created by the author who inspired `dotnet-delice`. + +## Unresolved Questions + +- ❔ How do we handle packages that don't use the `license` field? Especially if they are outdated versions a package. +- ❔ Should there be a common output approach with the npm solution to support interop? + +## Future Possibilities + +N/A From ad0a81a73575e36ebf8d39f39478299f0ee6c72e Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Tue, 11 May 2021 16:19:10 +1000 Subject: [PATCH 2/2] some wording tweaks --- proposed/2021/LicenseInspection.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/proposed/2021/LicenseInspection.md b/proposed/2021/LicenseInspection.md index 38d6dd784c..0b99cc0834 100644 --- a/proposed/2021/LicenseInspection.md +++ b/proposed/2021/LicenseInspection.md @@ -11,18 +11,18 @@ This command will allow someone to inspect all the licenses that are specified f ## Motivation -The motivation is to give people more insights into the licenses that are used in a project, ensuring they can stay compliant with the licenses. +The motivation is to give people more insights into the licenses that are used in a project, ensuring they can stay on top of compliancy requirements. ## Explanation -### Functional explanation - On the new project you're building, there are dependencies on NuGet packages from a remote feed, and those packages in turn have their own dependencies. This has resulted in an opaque view of what licenses are being consumed by the project. Your companies legal department has outlined a list of open source licenses that it is comfortable consuming and others that it wants to avoid using. To avoid accidentally consuming an unsupported license we need a way to view the list and ideally fail builds when we use one of these licenses. +### Functional explanation + #### Local scenario You have just added a new NuGet dependency into the project and want to ensure it doesn't bring in any unsupported licenses. @@ -60,14 +60,14 @@ Satisfied with the licenses, you continue on with the task at hand. #### Blocking builds -It's time to update our build pipeline to avoid releasing anything changes that introduce unsupported licenses. A new step is added to the pipeline YAML: +It's time to update your build pipeline to avoid releasing anything changes that introduce unsupported licenses. A new step is added to the pipeline YAML: ```yml - name: Validate Licenses runs: | LICENSES=$(dotnet nuget license --json | jq '') if ($LICENSES) then - exit 0 + exit 1 fi ``` @@ -75,9 +75,9 @@ This (pseduocode version) will dump the licenses to a JSON structure that can be ### Technical explanation -The first technical challenge for this is the inconsistent nature of which licenses are provided by NuGet packages. While the [`licenseUrl` field was deprecated](https://github.com/NuGet/Announcements/issues/32) a large number of packages still haven't adopted the new format, making it difficult to determine what the license of a project is. +The first technical challenge for this is the inconsistent nature of which licenses are provided by NuGet packages. While the [`licenseUrl` field was deprecated](https://github.com/NuGet/Announcements/issues/32), some projects haven't adopted the new format (or older packages that predate the deprecation are in use), making it difficult to determine what the license of a project is. -The next challenge is how to detect licenses from license files. The ideal approach would be to mirror GitHub's approach, which uses [Licensee](https://licensee.github.io/licensee/) [for detection](https://help.github.com/en/articles/licensing-a-repository#detecting-a-license) (but naturally a dotnet implementation). Essentially this uses [Sørensen–Dice coefficient](https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient) with a threshold for what is the acceptable level of comparison between the provided license and license template. +The next challenge is how to detect licenses from license files. The ideal approach would be to mirror GitHub's approach, which uses [Licensee](https://licensee.github.io/licensee/) [for detection](https://help.github.com/en/articles/licensing-a-repository#detecting-a-license) (but naturally a dotnet implementation). Essentially, this uses [Sørensen–Dice coefficient](https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient) with a threshold for what is the acceptable level of comparison between the package's license file and license template. The technical workflow for license detection would follow: @@ -111,7 +111,7 @@ It may also be worth having the facility to cache the SPDX license information f ## Drawbacks -Not having functionality to do this will result in users having to rely on third-party tooling, manually resolving the information themselves or being unaware they may break license restrictions. +Not having functionality to do this will result in users having to rely on third-party tooling, manually resolving the information or being unaware they may break license restrictions. ## Rationale and alternatives @@ -119,7 +119,7 @@ The rationale is to give people as much information as possible about the OSS th ## Prior Art -I have created a dotnet global tool that does this, [`dotnet-delice`](https://github.com/aaronpowell/dotnet-delice). This does prove that it is a technical possibility to implement such a solution. +I have created a dotnet global tool that does this, [`dotnet-delice`](https://github.com/aaronpowell/dotnet-delice). This proves that it is a technical possibility to implement such a solution. There is a [similar proposal for npm](https://github.com/npm/rfcs/pull/182), created by the author who inspired `dotnet-delice`.