From 8177b78f421b0a55d842d6334af9415581af1656 Mon Sep 17 00:00:00 2001 From: Michael Stringer Date: Sun, 4 Jul 2021 12:11:58 +0100 Subject: [PATCH 1/4] WIP proposal for lockfile v2 --- build.sbt | 11 +- src/main/paradox/file-formats/index.md | 9 +- src/main/paradox/file-formats/version-1.md | 2 +- src/main/paradox/file-formats/version-2.md | 187 +++++++++++++++++++++ 4 files changed, 200 insertions(+), 9 deletions(-) create mode 100644 src/main/paradox/file-formats/version-2.md diff --git a/build.sbt b/build.sbt index b8fa3fa..9ce7449 100644 --- a/build.sbt +++ b/build.sbt @@ -20,7 +20,7 @@ organizationName := "Michael Stringer" startYear := Some(2019) licenses += ("Apache-2.0", url("https://www.apache.org/licenses/LICENSE-2.0.txt")) -scriptedLaunchOpts := { +scriptedLaunchOpts := { scriptedLaunchOpts.value ++ Seq("-Xmx1024M", "-Dplugin.version=" + version.value) } @@ -31,13 +31,14 @@ developers := List( Developer("stringbean", "Michael Stringer", "@the_stringbean", url("https://github.com/stringbean")), ) -homepage := Some(url("https://github.com/stringbean/sbt-dependency-lock")) -scmInfo := Some( +homepage := Some(url("https://github.com/stringbean/sbt-dependency-lock")) +scmInfo := Some( ScmInfo( url("https://github.com/stringbean/sbt-dependency-lock"), "https://github.com/stringbean/sbt-dependency-lock.git")) -git.remoteRepo := "git@github.com:stringbean/sbt-dependency-lock.git" -publishTo := sonatypePublishToBundle.value +git.remoteRepo := "git@github.com:stringbean/sbt-dependency-lock.git" +paradoxNavigationDepth := 3 +publishTo := sonatypePublishToBundle.value import sbtrelease.ReleasePlugin.autoImport.ReleaseTransformations.* diff --git a/src/main/paradox/file-formats/index.md b/src/main/paradox/file-formats/index.md index 4624169..e1ee988 100644 --- a/src/main/paradox/file-formats/index.md +++ b/src/main/paradox/file-formats/index.md @@ -4,12 +4,15 @@ _sbt-dependency-lock_ stores lockfile information in JSON format with a version top-level object. Details of the file format can be found on these pages, and we encourage other tools to utilise the output information. -| Version | Added In | Removed In | Description | -| ---------------------: | -------: | ---------: | ---------------- | -| @ref:[1](version-1.md) | 0.1.0 | _current_ | Initial version. | +| Version | Added In | Removed In | Description | +| ---------------------: | ---------: | ---------: | ------------------------- | +| @ref:[1](version-1.md) | 0.1.0 | _current_ | Initial version. | +| @ref:[2](version-2.md) | _proposed_ | _N/A_ | Proposed enhanced format. | + Current default version is: 1 @@@ index * [Version 1](version-1.md) +* [Version 2](version-2.md) @@@ \ No newline at end of file diff --git a/src/main/paradox/file-formats/version-1.md b/src/main/paradox/file-formats/version-1.md index b8c9915..9b386db 100644 --- a/src/main/paradox/file-formats/version-1.md +++ b/src/main/paradox/file-formats/version-1.md @@ -13,7 +13,7 @@ dependencies. #### lockVersion * **Type:** Integer. -* **Description:** Version of the lockfile - always 1. +* **Description:** Version of the lockfile: `1`. #### timestamp diff --git a/src/main/paradox/file-formats/version-2.md b/src/main/paradox/file-formats/version-2.md new file mode 100644 index 0000000..3a0fa95 --- /dev/null +++ b/src/main/paradox/file-formats/version-2.md @@ -0,0 +1,187 @@ +# Version 2 + +* **Added in:** _N/A_ +* **Removed in:** _N/A_ + +@@@warning +This version of the lockfile is currently a proposal and has not been implemented yet. + +This will be added in version 2.0.0. +@@@ + +## Types + +### Lockfile + +Top level object for a project lockfile. Contains details of the build configurations and a list of the resolved +dependencies. + +#### lockVersion + +* **Type:** Integer. +* **Description:** Version of the lockfile: `2`. + +#### timestamp + +* **Type:** String (timestamp) or `null`. +* **Description:** File generation timestamp in ISO 8601 format (or `null` if timestamps are disabled). + +#### configurations + +* **Type:** Array of strings. +* **Description:** List of sbt build configurations in the current project. + +#### dependencies + +* **Type:** Array of `Dependency`. +* **Description:** List of all the dependencies in the current project. + +### Dependency + +Details of a resolved dependency. + +#### org + +* **Type:** String. +* **Description:** Organisation of the resolved dependency from Ivy/Maven. + +#### name + +* **Type:** String. +* **Description:** Name of the resolved dependency from Ivy/Maven. + +#### version + +* **Type:** String. +* **Description:** Version of the resolved dependency. + +#### artifacts + +* **Type:** Array of `Artifact`. +* **Description:** List of all the artifacts for the dependency. +* **Note:** Currently only `jar` artifacts are included. + +#### configurations + +* **Type:** Array of strings. +* **Description:** List of the sbt configurations that include this dependency. + +### Artifact + +Details of an artifact contained within a dependency. + +#### name + +* **Type:** String. +* **Description:** Filename of the artifact. + +#### hash + +* **Type:** String (checksum). +* **Description:** Checksum of the artifact prefixed with the checksum algorithm. +* **Note:** Currently only `sha1` is supported. + +## Changes from Version 1 + +### Timestamp is optional + +Previously the `timestamp` field was always included which could cause merge conflicts for some projects. From version 2 +onwards this can now be set to `null` if timestamps are disabled. + +Before: + +```json +{ + "version": 1, + "timestamp": "2019-10-29T17:33:05.944Z" +} +``` + +After: + +```json +{ + "version": 2, + "timestamp": null +} +``` + +### Support for Multiple Checksum Hashes + +Version 1 only supported a single hashing algorithm (SHA-1). From version 2 support for storing multiple hashes in the +lockfile has been added. This allows for more flexibility and phasing in of new hashes in a backwards compatible way. + +Before: + +```json +{ + "org": "org.apache.commons", + "name": "commons-lang3", + "version": "3.9", + "artifacts": [ + { + "name": "commons-lang3.jar", + "hash": "sha1:0122c7cee69b53ed4a7681c03d4ee4c0e2765da5" + } + ] +} +``` + +After: + +```json +{ + "org": "org.apache.commons", + "name": "commons-lang3", + "version": "3.9", + "artifacts": [ + { + "name": "commons-lang3.jar", + "hash": { + "sha1": "0122c7cee69b53ed4a7681c03d4ee4c0e2765da5", + "sha256": "de2e1dcdcf3ef917a8ce858661a06726a9a944f28e33ad7f9e08bea44dc3c230" + } + } + ] +} +``` +### Additional Metadata in Artifacts + +Two new fields have been added to the 'Artifact' type: + +- `url` - the URL that the artifact was fetched from. +- `license` - SPDX identifier of the license for the artifact. + +These make it easier for other tools to perform actions relating to dependencies. + +Before: + +```json +{ + "org": "org.apache.commons", + "name": "commons-lang3", + "version": "3.9", + "artifacts": [ + { + "name": "commons-lang3.jar" + } + ] +} +``` + +After: + +```json +{ + "org": "org.apache.commons", + "name": "commons-lang3", + "version": "3.9", + "artifacts": [ + { + "name": "commons-lang3.jar", + "url": "https://repo1.maven.org/maven2/org/apache/commons/commons-lang3/3.9/commons-lang3-3.9.jar", + "license": "Apache-2.0" + } + ] +} +``` From e6b14b84dd361e53b9bdbe4304fe90de386fcb8f Mon Sep 17 00:00:00 2001 From: Michael Stringer Date: Thu, 4 Jul 2024 11:40:39 +0100 Subject: [PATCH 2/4] Add JSON schemas --- src/main/paradox/file-formats/version-1.md | 1 + src/main/paradox/file-formats/version-2.md | 63 +++++++++++++ src/main/paradox/lockfile-v1.schema.json | 93 ++++++++++++++++++ src/main/paradox/lockfile-v2.schema.json | 105 +++++++++++++++++++++ 4 files changed, 262 insertions(+) create mode 100644 src/main/paradox/lockfile-v1.schema.json create mode 100644 src/main/paradox/lockfile-v2.schema.json diff --git a/src/main/paradox/file-formats/version-1.md b/src/main/paradox/file-formats/version-1.md index 9b386db..525b120 100644 --- a/src/main/paradox/file-formats/version-1.md +++ b/src/main/paradox/file-formats/version-1.md @@ -2,6 +2,7 @@ * **Added in:** 0.1.0 * **Removed in:** _N/A_ +* **Schema:** [lockfile-v1.schema.json](../lockfile-v1.schema.json) ## Types diff --git a/src/main/paradox/file-formats/version-2.md b/src/main/paradox/file-formats/version-2.md index 3a0fa95..85b979b 100644 --- a/src/main/paradox/file-formats/version-2.md +++ b/src/main/paradox/file-formats/version-2.md @@ -2,6 +2,7 @@ * **Added in:** _N/A_ * **Removed in:** _N/A_ +* **Schema:** [lockfile-v2.schema.json](../lockfile-v2.schema.json) @@@warning This version of the lockfile is currently a proposal and has not been implemented yet. @@ -185,3 +186,65 @@ After: ] } ``` + +## Examples + +```json +{ + "lockVersion": 2, + "timestamp": "2024-06-04T17:33:05.944Z", + "configurations": [ + "compile", + "optional", + "provided", + "runtime", + "test" + ], + "dependencies": [ + { + "org": "org.apache.commons", + "name": "commons-lang3", + "version": "3.9", + "license": "Apache-2.0", + "artifacts": [ + { + "name": "commons-lang3.jar", + "url": "https://repo1.maven.org/maven2/org/apache/commons/commons-lang3/3.9/commons-lang3-3.9.jar", + "hash": { + "sha1": "0122c7cee69b53ed4a7681c03d4ee4c0e2765da5", + "sha256": "de2e1dcdcf3ef917a8ce858661a06726a9a944f28e33ad7f9e08bea44dc3c230" + } + } + ], + "configurations": [ + "test", + "compile", + "runtime" + ] + }, + { + "org": "org.scala-lang", + "name": "scala-library", + "version": "2.12.10", + "license": "Apache-2.0", + "artifacts": [ + { + "name": "scala-library.jar", + "url": "https://repo1.maven.org/maven2/org/scala-lang/scala-library/2.12.10/scala-library-2.12.10.jar", + "hash": { + "sha1": "3509860bc2e5b3da001ed45aca94ffbe5694dbda", + "sha256": "0a57044d10895f8d3dd66ad4286891f607169d948845ac51e17b4c1cf0ab569d" + } + } + ], + "configurations": [ + "test", + "compile", + "runtime" + ] + } + ] +} +``` + + diff --git a/src/main/paradox/lockfile-v1.schema.json b/src/main/paradox/lockfile-v1.schema.json new file mode 100644 index 0000000..eece562 --- /dev/null +++ b/src/main/paradox/lockfile-v1.schema.json @@ -0,0 +1,93 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://stringbean.github.io/sbt-dependency-lock/lockfile-v1.schema.json", + "title": "sbt-dependency-lock lockfile v1", + "description": "Lockfile for sbt-dependency-lock - version 1 format", + "type": "object", + "required": [ + "lockVersion", + "timestamp", + "configurations", + "dependencies" + ], + "properties": { + "lockVersion": { + "type": "integer", + "description": "Version of the lockfile" + }, + "timestamp": { + "type": "string", + "format": "date-time", + "description": "File generation timestamp" + }, + "configurations": { + "type": "array", + "description": "List of sbt build configurations in the current project", + "items": { + "type": "string" + } + }, + "dependencies": { + "type": "array", + "description": "List of all the dependencies in the current project", + "items": { + "required": [ + "org", + "name", + "version", + "artifacts" + ], + "properties": { + "org": { + "type": "string", + "description": "Organisation of the resolved dependency from Ivy/Maven" + }, + "name": { + "type": "string", + "description": "Name of the resolved dependency from Ivy/Maven" + }, + "version": { + "type": "string", + "description": "Version of the resolved dependency" + }, + "artifacts": { + "type": "array", + "description": "List of all the artifacts for the dependency", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Filename of the artifact", + "examples": [ + "commons-lang3.jar" + ] + }, + "hash": { + "type": "string", + "description": "Checksum of the artifact prefixed with the checksum algorithm", + "examples": [ + "sha1:0122c7cee69b53ed4a7681c03d4ee4c0e2765da5" + ] + } + } + } + }, + "configurations": { + "type": "array", + "description": "List of the sbt configurations that include this dependency", + "items": { + "type": "string", + "examples": [ + [ + "compile", + "test" + ] + ] + } + } + } + } + } + } +} \ No newline at end of file diff --git a/src/main/paradox/lockfile-v2.schema.json b/src/main/paradox/lockfile-v2.schema.json new file mode 100644 index 0000000..e2eaa3b --- /dev/null +++ b/src/main/paradox/lockfile-v2.schema.json @@ -0,0 +1,105 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://stringbean.github.io/sbt-dependency-lock/lockfile-v2.schema.json", + "title": "sbt-dependency-lock lockfile v2", + "description": "Lockfile for sbt-dependency-lock - version 2 format", + "type": "object", + "required": [ + "lockVersion", + "timestamp", + "configurations", + "dependencies" + ], + "properties": { + "lockVersion": { + "type": "integer", + "description": "Version of the lockfile" + }, + "timestamp": { + "type": "string", + "format": "date-time", + "description": "File generation timestamp" + }, + "configurations": { + "type": "array", + "description": "List of sbt build configurations in the current project", + "items": { + "type": "string" + } + }, + "dependencies": { + "type": "array", + "description": "List of all the dependencies in the current project", + "items": { + "required": [ + "org", + "name", + "version", + "artifacts" + ], + "properties": { + "org": { + "type": "string", + "description": "Organisation of the resolved dependency from Ivy/Maven" + }, + "name": { + "type": "string", + "description": "Name of the resolved dependency from Ivy/Maven" + }, + "version": { + "type": "string", + "description": "Version of the resolved dependency" + }, + "license": { + "type": "string", + "description": "License of the dependency (in SPDX identifier format)" + }, + "artifacts": { + "type": "array", + "description": "List of all the artifacts for the dependency", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Filename of the artifact", + "examples": [ + "commons-lang3.jar" + ] + }, + "hash": { + "type": "object", + "description": "Checksum of the artifact using different algorithms", + "items": true, + "required": [ + "sha1", + "sha256" + ], + "examples": [ + { + "sha1": "3509860bc2e5b3da001ed45aca94ffbe5694dbda", + "sha256": "0a57044d10895f8d3dd66ad4286891f607169d948845ac51e17b4c1cf0ab569d" + } + ] + } + } + } + }, + "configurations": { + "type": "array", + "description": "List of the sbt configurations that include this dependency", + "items": { + "type": "string", + "examples": [ + [ + "compile", + "test" + ] + ] + } + } + } + } + } + } +} \ No newline at end of file From 0ad3bd1ef5e60f37b43a378d974122592cfd5c47 Mon Sep 17 00:00:00 2001 From: Michael Stringer Date: Sat, 6 Jul 2024 13:59:03 +0100 Subject: [PATCH 3/4] More tweaks to v2 docs --- src/main/paradox/file-formats/version-2.md | 101 +++++++++++++++++++-- 1 file changed, 92 insertions(+), 9 deletions(-) diff --git a/src/main/paradox/file-formats/version-2.md b/src/main/paradox/file-formats/version-2.md index 85b979b..6b97844 100644 --- a/src/main/paradox/file-formats/version-2.md +++ b/src/main/paradox/file-formats/version-2.md @@ -56,6 +56,11 @@ Details of a resolved dependency. * **Type:** String. * **Description:** Version of the resolved dependency. +#### license + +* **Type:** String. +* **Description:** License of the dependency (in SPDX identifier format). + #### artifacts * **Type:** Array of `Artifact`. @@ -78,9 +83,24 @@ Details of an artifact contained within a dependency. #### hash -* **Type:** String (checksum). +* **Type:** Array of `Artifact Hash`. * **Description:** Checksum of the artifact prefixed with the checksum algorithm. -* **Note:** Currently only `sha1` is supported. + + +### Artifact Hash + +Checksums for a dependency artifact. This is an object that contains one or more hashes for the artifact, currently only +SHA-1 and SHA-256 are supported but more may be added in the future. + +#### sha1 + +* **Type:** String. +* **Description:** SHA-1 hash of the artifact. + +#### sha256 + +* **Type:** String. +* **Description:** SHA-256 hash of the artifact. ## Changes from Version 1 @@ -146,14 +166,39 @@ After: ] } ``` -### Additional Metadata in Artifacts -Two new fields have been added to the 'Artifact' type: +### License Metadata for Dependencies -- `url` - the URL that the artifact was fetched from. -- `license` - SPDX identifier of the license for the artifact. +The license of each dependency has been added to the `Dependency` type. This makes it easier for other tooling to +inspect the licenses used by a project. -These make it easier for other tools to perform actions relating to dependencies. +Before: + +```json +{ + "org": "org.apache.commons", + "name": "commons-lang3", + "version": "3.9", + "artifacts": [...] +} +``` + +After: + +```json +{ + "org": "org.apache.commons", + "name": "commons-lang3", + "version": "3.9", + "license": "Apache-2.0", + "artifacts": [...] +} +``` + +### Source URL Metadata for Artifacts + +The source URL of each artifact has been added to the `Artifact` type. This allows other tooling to download the +artifacts resolved by sbt. Before: @@ -180,8 +225,7 @@ After: "artifacts": [ { "name": "commons-lang3.jar", - "url": "https://repo1.maven.org/maven2/org/apache/commons/commons-lang3/3.9/commons-lang3-3.9.jar", - "license": "Apache-2.0" + "url": "https://repo1.maven.org/maven2/org/apache/commons/commons-lang3/3.9/commons-lang3-3.9.jar" } ] } @@ -189,6 +233,8 @@ After: ## Examples +### With Timestamp + ```json { "lockVersion": 2, @@ -247,4 +293,41 @@ After: } ``` +### Without Timestamp +```json +{ + "lockVersion": 2, + "timestamp": null, + "configurations": [ + "compile", + "optional", + "provided", + "runtime", + "test" + ], + "dependencies": [ + { + "org": "org.scala-lang", + "name": "scala-library", + "version": "2.12.10", + "license": "Apache-2.0", + "artifacts": [ + { + "name": "scala-library.jar", + "url": "https://repo1.maven.org/maven2/org/scala-lang/scala-library/2.12.10/scala-library-2.12.10.jar", + "hash": { + "sha1": "3509860bc2e5b3da001ed45aca94ffbe5694dbda", + "sha256": "0a57044d10895f8d3dd66ad4286891f607169d948845ac51e17b4c1cf0ab569d" + } + } + ], + "configurations": [ + "test", + "compile", + "runtime" + ] + } + ] +} +``` From 457cfe2e4fdbe14c7961f9e1d8870ca7950cd5db Mon Sep 17 00:00:00 2001 From: Michael Stringer Date: Sat, 6 Jul 2024 14:06:55 +0100 Subject: [PATCH 4/4] Make it clearer in nav that v2 is a proposal --- src/main/paradox/file-formats/version-1.md | 2 +- src/main/paradox/file-formats/version-2.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/main/paradox/file-formats/version-1.md b/src/main/paradox/file-formats/version-1.md index 525b120..5cf3be9 100644 --- a/src/main/paradox/file-formats/version-1.md +++ b/src/main/paradox/file-formats/version-1.md @@ -1,4 +1,4 @@ -# Version 1 +# Version 1 (current) * **Added in:** 0.1.0 * **Removed in:** _N/A_ diff --git a/src/main/paradox/file-formats/version-2.md b/src/main/paradox/file-formats/version-2.md index 6b97844..78e9826 100644 --- a/src/main/paradox/file-formats/version-2.md +++ b/src/main/paradox/file-formats/version-2.md @@ -1,4 +1,4 @@ -# Version 2 +# Version 2 (proposal) * **Added in:** _N/A_ * **Removed in:** _N/A_