Skip to content

Commit 5157549

Browse files
stringbeanstringbean
authored
Add initial docs (#7)
1 parent 7eb32f4 commit 5157549

File tree

8 files changed

+301
-6
lines changed

8 files changed

+301
-6
lines changed

‎README.md‎

Lines changed: 32 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,35 @@
1-
# sbt-dependency-lock
1+
# sbt-dependency-lock
2+
[![Build Status](https://travis-ci.com/stringbean/sbt-dependency-lock.svg?branch=master)](https://travis-ci.com/stringbean/sbt-dependency-lock)
3+
[![Codacy grade](https://img.shields.io/codacy/grade/d45ca406c90c45c88a3a317563bc3302?label=codacy)](https://codacy.com/app/stringbean/sbt-dependency-lock)
4+
![Bintray](https://img.shields.io/bintray/v/stringbean/sbt-plugins/sbt-dependency-lock?label=sbt%201.x)
25

3-
An sbt plugin to create a dependency lockfile
6+
An sbt plugin to create a dependency lockfile similar to `package-lock.json` for npm or `Gemfile.lock` for RubyGems.
47

5-
## Usage
8+
## Quickstart
69

7-
This plugin requires sbt 1.0.0+
10+
Install the plugin by adding the following to `project/plugins.sbt`:
11+
12+
```scala
13+
addSbtPlugin("software.purpledragon" % "sbt-dependency-lock" % "<version>")
14+
```
15+
16+
And then generate a lock file with `sbt dependencyLockWrite`. This will resolve dependencies and output a lockfile
17+
containing all dependencies (including transitive ones) to `build.sbt.lock`.
18+
19+
The lockfile can then be checked with `sbt dependencyLockCheck`:
20+
21+
```text
22+
[info] Dependency lock check passed
23+
```
24+
25+
A mismatch between the lockfile and current dependencies will generate an error report:
26+
27+
```text
28+
[error] (dependencyLockCheck) Dependency lock check failed:
29+
[error] 3 dependencies changed:
30+
[error] org.scala-lang.modules:scala-xml_2.12:[1.2.0]->[1.1.0] (test)
31+
[error] org.scalactic:scalactic_2.12:[3.0.8]->[3.0.7] (test)
32+
[error] org.scalatest:scalatest_2.12:[3.0.8]->[3.0.7] (test)
33+
```
34+
35+
See the [docs](https://stringbean.github.io/sbt-dependency-lock) for further information on how the plugin works.

‎build.sbt‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
11
name := "sbt-dependency-lock"
22
organization := "software.purpledragon"
33

4-
enablePlugins(SbtPlugin)
4+
enablePlugins(
5+
SbtPlugin,
6+
ParadoxSitePlugin,
7+
GhpagesPlugin)
58

69
// target sbt 1.2.8 to allow 1.0+ compatibility
710
pluginCrossBuild / sbtVersion := "1.2.8"
@@ -37,6 +40,7 @@ scmInfo := Some(
3740
ScmInfo(
3841
url("https://github.com/stringbean/sbt-dependency-lock"),
3942
"https://github.com/stringbean/sbt-dependency-lock.git"))
43+
git.remoteRepo := "[email protected]:stringbean/sbt-dependency-lock.git"
4044

4145
bintrayPackageLabels := Seq("sbt", "sbt-plugin", "lockfile")
4246

@@ -54,6 +58,7 @@ releaseProcess := Seq[ReleaseStep](
5458
commitReleaseVersion,
5559
tagRelease,
5660
publishArtifacts,
61+
releaseStepTask(ghpagesPushSite),
5762
setNextVersion,
5863
commitNextVersion,
5964
pushChanges

‎project/plugins.sbt‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
1+
// publishing
12
addSbtPlugin("com.jsuereth" % "sbt-pgp" % "1.1.1")
23
addSbtPlugin("org.foundweekends" % "sbt-bintray" % "0.5.4")
34
addSbtPlugin("com.github.gseitz" % "sbt-release" % "1.0.12")
45

6+
// code style
57
addSbtPlugin("de.heikoseeberger" % "sbt-header" % "5.2.0")
6-
addSbtPlugin("com.sksamuel.scapegoat" %% "sbt-scapegoat" % "1.0.9")
8+
addSbtPlugin("com.sksamuel.scapegoat" %% "sbt-scapegoat" % "1.0.9")
9+
10+
// documentation
11+
addSbtPlugin("com.typesafe.sbt" % "sbt-site" % "1.4.0")
12+
addSbtPlugin("com.lightbend.paradox" % "sbt-paradox" % "0.6.8")
13+
addSbtPlugin("com.typesafe.sbt" % "sbt-ghpages" % "0.6.3")

‎src/main/paradox/file-formats/index.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# File Formats
2+
3+
_sbt-dependency-lock_ stores lockfile information in JSON format with a version identifier (`lockVersion`) in the
4+
top-level object. Details of the file format can be found on these pages, and we encourage other tools to utilise the
5+
output information.
6+
7+
| Version | Added In | Removed In | Description |
8+
| ---------------------: | -------: | ---------: | ---------------- |
9+
| @ref:[1](version-1.md) | 0.1.0 | _current_ | Initial version. |
10+
11+
Current default version is: 1
12+
13+
@@@ index
14+
* [Version 1](version-1.md)
15+
@@@

‎src/main/paradox/file-formats/version-1.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Version 1
2+
3+
@@@warning
4+
This version of the lockfile has not been finalised and may change as features are added or bugs resolved.
5+
6+
The format will be finalised in version 1.0.0.
7+
@@@
8+
9+
* **Added in:** 0.1.0
10+
* **Removed in:** _N/A_
11+
12+
## Types
13+
14+
### Lockfile
15+
16+
Top level object for a project lockfile. Contains details of the build configurations and a list of the resolved
17+
dependencies.
18+
19+
#### lockVersion
20+
21+
* **Type:** Integer.
22+
* **Description:** Version of the lockfile - always 1.
23+
24+
#### timestamp
25+
26+
* **Type:** String (timestamp).
27+
* **Description:** File generation timestamp in ISO 8601 format.
28+
29+
#### configurations
30+
31+
* **Type:** Array of strings.
32+
* **Description:** List of sbt build configurations in the current project.
33+
34+
#### dependencies
35+
36+
* **Type:** Array of `Dependency`.
37+
* **Description:** List of all the dependencies in the current project.
38+
39+
### Dependency
40+
41+
Details of a resolved dependency.
42+
43+
#### org
44+
45+
* **Type:** String.
46+
* **Description:** Organisation of the resolved dependency from Ivy/Maven.
47+
48+
#### name
49+
50+
* **Type:** String.
51+
* **Description:** Name of the resolved dependency from Ivy/Maven.
52+
53+
#### version
54+
55+
* **Type:** String.
56+
* **Description:** Version of the resolved dependency.
57+
58+
#### artifacts
59+
60+
* **Type:** Array of `Artifact`.
61+
* **Description:** List of all the artifacts for the dependency.
62+
* **Note:** Currently only `jar` artifacts are included.
63+
64+
#### configurations
65+
66+
* **Type:** Array of strings.
67+
* **Description:** List of the sbt configurations that include this dependency.
68+
69+
### Artifact
70+
71+
Details of an artifact contained within a dependency.
72+
73+
#### name
74+
75+
* **Type:** String.
76+
* **Description:** Filename of the artifact.
77+
78+
#### hash
79+
80+
* **Type:** String (checksum).
81+
* **Description:** Checksum of the artifact prefixed with the checksum algorithm.
82+
* **Note:** Currently only `sha1` is supported.
83+
84+
## Example
85+
86+
```json
87+
{
88+
"lockVersion" : 1,
89+
"timestamp" : "2019-10-29T17:33:05.944Z",
90+
"configurations" : [
91+
"compile",
92+
"optional",
93+
"provided",
94+
"runtime",
95+
"test"
96+
],
97+
"dependencies" : [
98+
{
99+
"org" : "org.apache.commons",
100+
"name" : "commons-lang3",
101+
"version" : "3.9",
102+
"artifacts" : [
103+
{
104+
"name" : "commons-lang3.jar",
105+
"hash" : "sha1:0122c7cee69b53ed4a7681c03d4ee4c0e2765da5"
106+
}
107+
],
108+
"configurations" : [
109+
"test",
110+
"compile",
111+
"runtime"
112+
]
113+
},
114+
{
115+
"org" : "org.scala-lang",
116+
"name" : "scala-library",
117+
"version" : "2.12.10",
118+
"artifacts" : [
119+
{
120+
"name" : "scala-library.jar",
121+
"hash" : "sha1:3509860bc2e5b3da001ed45aca94ffbe5694dbda"
122+
}
123+
],
124+
"configurations" : [
125+
"test",
126+
"compile",
127+
"runtime"
128+
]
129+
}
130+
]
131+
}
132+
```

‎src/main/paradox/getting-started.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Getting Started
2+
3+
## Setup
4+
5+
Install the plugin by adding the following to `project/plugins.sbt`:
6+
7+
@@@vars
8+
```scala
9+
addSbtPlugin("software.purpledragon" % "sbt-dependency-lock" % "$project.version$")
10+
```
11+
@@@
12+
13+
And then generate a lock file with `sbt dependencyLockWrite`. This will resolve dependencies and output a lockfile
14+
containing all dependencies (including transitive ones) to `build.sbt.lock`.
15+
16+
@@@ note
17+
The generated `build.sbt.lock` file should be checked into source control with the rest of the project source code.
18+
@@@
19+
20+
## Checking for Dependency Changes
21+
22+
The status of the lockfile can be checked using the `dependencyLockCheck` which will resolve the current dependencies
23+
and check them against the lockfile.
24+
25+
### Valid Lockfile
26+
27+
If the lockfile and current dependencies match then a success message will be printed, and the build will succeed:
28+
29+
```text
30+
[info] Dependency lock check passed
31+
```
32+
33+
### Missing Lockfile
34+
35+
If no lockfile can be found then an error will be printed, and the build will fail:
36+
37+
```text
38+
[error] (dependencyLockCheck) no lock file
39+
```
40+
41+
### Lockfile Mismatch
42+
43+
A mismatch between the lockfile and current dependencies will generate an error report summarising the differences:
44+
45+
```text
46+
[error] (dependencyLockCheck) Dependency lock check failed:
47+
[error] 3 dependencies changed:
48+
[error] org.apache.commons:commons-lang3:3.9 (test)->(compile,test)
49+
[error] org.scala-lang.modules:scala-xml_2.12:[1.2.0]->[1.1.0] (test)
50+
[error] org.scalactic:scalactic_2.12:[3.0.8]->[3.0.7] (test)
51+
[error] org.scalatest:scalatest_2.12:[3.0.8]->[3.0.7] (test)
52+
```
53+
54+
The error report is broken down into a number of sections:
55+
56+
1. Configurations added:
57+
```text
58+
1 config added: it
59+
```
60+
2. Configurations removed:
61+
```text
62+
2 configs removed: it,war
63+
```
64+
3. Dependencies added:
65+
```text
66+
2 dependencies added:
67+
com.example:artifact1:1.0 (compile)
68+
com.example:artifact2:1.2 (test)
69+
```
70+
4. Dependencies removed:
71+
```text
72+
1 dependency removed:
73+
com.example:artifact3:3.1.1 (runtime)
74+
```
75+
5. Changed dependencies:
76+
```text
77+
3 dependencies changed:
78+
org.example:version:[1.0]->[2.0] (compile)
79+
org.example:configs:1.0 (compile,test)->(compile)
80+
org.example:both:[1.0]->[2.0] (compile)->(compile,test)
81+
```

‎src/main/paradox/index.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# sbt-dependency-lock
2+
3+
Generate dependency lockfiles for sbt projects similar to `package-lock.json` or `Gemfile.lock`.
4+
5+
## Rationale
6+
7+
Managing dependencies on a large project can be a difficult problem especially when requested dependencies pull in large
8+
numbers of transitive dependencies. This can lead to scenarios where incrementing the version of a single dependency can
9+
cause a snowball effect of dozens of updated transitive dependencies.
10+
11+
This plugin generates a lockfile based on the current project dependencies that can be checked into source control and
12+
can be checked to see what dependencies have changed.
13+
14+
@@@ index
15+
* [Getting Started](getting-started.md)
16+
* [Settings](settings.md)
17+
* [File Formats](file-formats/index.md)
18+
@@@

‎src/main/paradox/settings.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Settings Reference
2+
3+
## Settings
4+
5+
### dependencyLockFile
6+
7+
* **Description:** Filename of generated lockfile.
8+
* **Accepts:** `java.io.File`
9+
* **Default:** `baseDirectory.value / "build.sbt.lock"`

0 commit comments

Comments
 (0)