1- ** sbt-git-versioning** is an sbt plugin designed to make maintaining a simple, consistent, and accurate
1+ ** sbt-git-versioning** is a suite of sbt plugins designed to make maintaining a simple, consistent, and accurate
22 [ semantic versioning] ( http://semver.org/spec/v2.0.0.html ) scheme with as little manual labor as possible.
33
44There are two sbt plugins in this one plugin library:
5- * [ GitVersioningPlugin] ( src/main/scala/com/rallyhealth/sbt/versioning/ GitVersioningPlugin.scala )
6- * [ SemVerPlugin] ( src/main/scala/com/rallyhealth/sbt/semver/ SemVerPlugin.scala )
5+ * [ GitVersioningPlugin] ( # GitVersioningPlugin)
6+ * [ SemVerPlugin] ( # SemVerPlugin)
77
88# Compatibility
99
@@ -14,9 +14,7 @@ Tested and supported for sbt version 0.13.x and above.
14141 . Remove the ` version := ... ` directive from the project's ` build.sbt ` file
15152 . Add the following code to ` project/plugins.sbt ` file (if you want to use Ivy style resolution):
1616``` scala
17- resolvers += Resolver .url(
18- " Rally Plugin Releases" ,
19- url(" https://dl.bintray.com/rallyhealth/sbt-plugins" ))(Resolver .ivyStylePatterns)
17+ resolvers += Resolver .bintrayIvyRepo(" rallyhealth" , " sbt-plugins" )
2018```
2119Alternatively, you can add the following (if you want to use Maven style resolution):
2220``` scala
@@ -26,20 +24,16 @@ In either case, you should now be able to add the plugin dependency to `project/
2624``` scala
2725 addSbtPlugin(" com.rallyhealth.sbt" % " sbt-git-versioning" % " x.y.z" )
2826```
29- 3 . Enable the plugin and set ` semVerLimit ` in ` build.sbt ` (see
30- [ below] ( https://github.com/rallyhealth/sbt-git-versioning#semverlimit )
31- for details)
27+ 3 . Enable the plugin.
3228
3329``` scala
3430val example = project
3531 .enablePlugins(SemVerPlugin )
36- // See https://github.com/rallyhealth/sbt-git-versioning#semverlimit
37- .settings(semVerLimit := " x.y.z" )
3832```
3933
4034# GitVersioningPlugin
4135
42- This [ plugin ] ( src/main/scala/com/rallyhealth/sbt /versioning/GitVersioningPlugin.scala )
36+ [ GitVersioningPlugin ] ( blob/master/ src/main/scala/com/rallyhealth/versioning/GitVersioningPlugin.scala)
4337focuses on automatically determining the value of the ` version ` setting. The ` version ` is determined by looking at git history (for
4438previous tags) and the state of the working directly. Read on for the exact details.
4539
@@ -124,7 +118,6 @@ The release arg alters the value of `versionFromGit`, but is still bounded by `g
124118| 1.0.0 | major | 2.0.0 | 2.0.0 |
125119
126120#### Example
127-
128121With most recent git tag at ` v1.4.2 ` and a ` gitVersioningSnapshotLowerBound ` setting of:
129122```
130123gitVersioningSnapshotLowerBound in ThisBuild := "2.0.0"
@@ -155,23 +148,39 @@ ensure that any git plugins are configured to not use shallow clones.
155148
156149## Creating a Release
157150
158- Creating a release is done by tagging and then publishing a release...
159- ```
160- git tag v1.2.3
161- sbt publish[Local]
151+ ### Recommended: -Drelease
152+ Creating a release is done by passing a [ release arg] ( #release-arg-property ) .
162153```
154+ sbt -Drelease=patch publish[Local]
155+ ```
156+
157+ You can extract the version for other purposes (e.g. git tagging after successful publish) using the ` writeVersion <file> ` input task.
163158
164- ...or by passing a [ release arg] ( #release-arg-property ) .
159+ ``` bash
160+ export VERSIONFILE=$( mktemp) # avoid creating untracked files so version doesn't become -dirty.
161+ sbt " writeVersion $VERSIONFILE "
162+ export VERSION=$( cat $VERSIONFILE )
163+ git tag " v${VERSION} " "
164+ git push origin " v${VERSION} "
165+ # ...
165166` ` `
166- sbt -Drelease=patch publish[Local]
167+
168+ # ## Possible: tag + sbt-git-versioning
169+ ...or by tagging and then publishing a release...
170+ ` ` `
171+ git tag v1.2.3
172+ sbt publish[Local]
167173` ` `
168174
175+ # ## Not recommended (unless have good reasons): version.override
169176...or by overriding the version that will be applied to a specific build, using the
170177` version.override` setting. Typically this is done by at the command line to avoid changing ` build.sbt` .
171178` ` `
172179sbt -Dversion.override=1.2.3 publish[Local]
173180` ` `
174181
182+ You shouldn' t do this without good reason. Version determination can be complicated, because git can be complicated.
183+
175184## Extra Identifiers
176185
177186To add an extra identifier like "-alpha" or "-rc1" or "-rally" it must be included it in the version directly
@@ -180,7 +189,7 @@ removed because it was never used. Feel free to re-add it.)
180189
181190# SemVerPlugin
182191
183- This [ plugin ] ( src/main/scala/com/rallyhealth/sbt/semver/SemVerPlugin.scala )
192+ [SemVerPlugin](blob/master/ src/main/scala/com/rallyhealth/sbt/semver/SemVerPlugin.scala)
184193will halt the build (compile, publish, etc.) if your changes would not make a valid [semantic version](http://semver.org/spec/v2.0.0.html).
185194The plugin checks the previous release, your changes, and the `semVerLimitRelease` to ensure your changes are really
186195patch/minor/major changes if you want to release a patch/minor/major.
@@ -199,10 +208,10 @@ The output will look like this:
199208[info] [SemVer] Checking ENABLED with LIMIT target semVerLimit=3.0.0
200209[info] [SemVer] Check starting (prev=2.0.0 vs curr=3.0.0) ...
201210[warn] [SemVer] Errors total=4, backward=0, forward=4, required diffType=minor
202- [warn] [SemVer] (1/4) Forward -> method calamity()Double in class com.rallyhealth.semver.Equestria does not have a correspondent in previous version
203- [warn] [SemVer] (2/4) Forward -> method princessLuna()Double in class com.rallyhealth.semver.Equestria does not have a correspondent in previous version
204- [warn] [SemVer] (3/4) Forward -> method starlightGlimmer()Double in class com.rallyhealth.semver.Equestria does not have a correspondent in previous version
205- [warn] [SemVer] (4/4) Forward -> method velvetRemedy()Double in class com.rallyhealth.semver.Equestria does not have a correspondent in previous version
211+ [warn] [SemVer] (1/4) Forward -> method calamity()Double in class com.rallyhealth.sbt. semver.Equestria does not have a correspondent in previous version
212+ [warn] [SemVer] (2/4) Forward -> method princessLuna()Double in class com.rallyhealth.sbt. semver.Equestria does not have a correspondent in previous version
213+ [warn] [SemVer] (3/4) Forward -> method starlightGlimmer()Double in class com.rallyhealth.sbt. semver.Equestria does not have a correspondent in previous version
214+ [warn] [SemVer] (4/4) Forward -> method velvetRemedy()Double in class com.rallyhealth.sbt. semver.Equestria does not have a correspondent in previous version
206215[warn] [SemVer] version=3.0.0 PASSED: required diffType=Minor achieved
207216[success] Total time: 2 s, completed Nov 15, 2016 3:38:48 PM
208217```
@@ -212,29 +221,36 @@ When the SemVerPlugin halts the build it will look like:
212221[info] [SemVer] Checking ENABLED with LIMIT target semVerLimit=2.0.1
213222[info] [SemVer] Check starting (prev=2.0.0 vs curr=2.0.1) ...
214223[error] [SemVer] Errors total=4, backward=0, forward=4, required diffType=minor
215- [error] [SemVer] (1/4) Forward -> method calamity()Double in class com.rallyhealth.semver.Equestria does not have a correspondent in previous version
216- [error] [SemVer] (2/4) Forward -> method princessLuna()Double in class com.rallyhealth.semver.Equestria does not have a correspondent in previous version
217- [error] [SemVer] (3/4) Forward -> method starlightGlimmer()Double in class com.rallyhealth.semver.Equestria does not have a correspondent in previous version
218- [error] [SemVer] (4/4) Forward -> method velvetRemedy()Double in class com.rallyhealth.semver.Equestria does not have a correspondent in previous version
224+ [error] [SemVer] (1/4) Forward -> method calamity()Double in class com.rallyhealth.sbt. semver.Equestria does not have a correspondent in previous version
225+ [error] [SemVer] (2/4) Forward -> method princessLuna()Double in class com.rallyhealth.sbt. semver.Equestria does not have a correspondent in previous version
226+ [error] [SemVer] (3/4) Forward -> method starlightGlimmer()Double in class com.rallyhealth.sbt. semver.Equestria does not have a correspondent in previous version
227+ [error] [SemVer] (4/4) Forward -> method velvetRemedy()Double in class com.rallyhealth.sbt. semver.Equestria does not have a correspondent in previous version
219228[error] [SemVer] version=2.0.1 FAILED: required diffType=minor NOT achieved
220229java.lang.IllegalStateException: Proposed RELEASE version=2.0.1 FAILED SemVer rules, failing build
221- at com.rallyhealth.semver.SemVerHalter.haltBuild(SemVerHalter.scala:86)
230+ at com.rallyhealth.sbt. semver.SemVerHalter.haltBuild(SemVerHalter.scala:86)
222231 ...
223232[error] (*:compile) java.lang.IllegalStateException: Proposed RELEASE version=2.0.1 FAILED SemVer rules, failing build
224233[error] Total time: 2 s, completed Nov 15, 2016 3:27:36 PM
225234```
226235
227236### semVerLimit
228237
229- Before using the check (manually or automatically), you * must* set the ` semVerLimit ` key in your ` build.sbt ` .
230- This is a version (e.g. "1.2.3") that tells SemVerPlugin when to halt the build. It prevents you from making any
238+ `semVerLimit` is a version (e.g. "1.2.3") that tells SemVerPlugin when to halt the build. It prevents you from making any
231239compatibility changes that would *exceed* that version.
232240
241+ Defaults:
242+ - Release builds - same as version (version=1.2.3, semVerLimit=1.2.3).
243+ - Snapshot builds - set to highest version before next major release (version=1.2.3-SNAPSHOT, semVerLimit=1.999.999).
244+
245+ You may explicitly set `semVerLimit` to alter this behavior.
246+
247+ #### Examples
248+
233249This is best explained with an example. Let' s assume the latest tag is ` 1.2.3` :
234250
235251* ` semVerLimit := 1.2.3` - you won' t be able to make *any* changes
236252* `semVerLimit := 1.2.**999**` - you will be allowed to make *patch* changes.
237- * ` semVerLimit := 1.**999.999** ` - you will be allowed to make * minor or patch* changes.
253+ * `semVerLimit := 1.**999.999**` - you will be allowed to make *minor or patch* changes. (This is the default value.)
238254* `semVerLimit := ""` - you will be allowed to make *major, minor, or patch* changes (`semVerLimit` is disabled)
239255
240256Here are a few stories to illustrate how `semVerLimit` works.
@@ -249,7 +265,7 @@ Here are a few stories to illustrate how `semVerLimit` works.
249265
250266#### Minor Change (with a human error)
251267
252- 1 . Version is ` 1.2.4 ` (from above) and ` semVerLimit := 1.9.9 ` :
268+ 1. Version is `1.2.4` (from above) and `semVerLimit := 1.9.9` (the default value) :
2532692. Applejack wants to add a new method (minor change).
2542703. Applejack adds the new method, commits, PRs, and merges.
2552714. Applejack runs the release job for `1.2.4` but the release job fails.
@@ -258,7 +274,7 @@ Here are a few stories to illustrate how `semVerLimit` works.
258274
259275# ### A 'Big' Patch Change
260276
261- 1 . Version is ` 1.3.0 ` (from above) and ` semVerLimit := 1.9.9 ` :
277+ 1. Version is ` 1.3.0` (from above) and ` semVerLimit := 1.9.9` (the default value) :
2622782. Twilight Sparkle found a potential bug for an edge case, e.g. some
263279' undefined' behavior. She only needs to make a * patch* change, but
264280someone could be relying on that ' undefined' behavior, she wants to release
@@ -270,7 +286,7 @@ change even though only *patch* was required)
270286
271287# ### Hot Fix (patch change)
272288
273- 1 . Version is ` 1.4.0 ` (from above) and ` semVerLimit := 1.9.9 ` :
289+ 1. Version is ` 1.4.0` (from above) and ` semVerLimit := 1.9.9` (the default value) :
2742902. Rainbow Dash needs to make a hot fix.
2752913. Rainbow Dash changes ` semVerLimit := 1.4.1` so she' s absolutely sure no minor changes sneak in.
2762924. Rainbow Dash makes her fix, commits, PRs, and merges
@@ -280,7 +296,7 @@ change even though only *patch* was required)
280296
281297#### Hot Fix Redux (patch change)
282298
283- 1 . Version is ` 1.4.1 ` (from above) and ` semVerLimit := 1.9.9 ` :
299+ 1. Version is `1.4.1` (from above) and `semVerLimit := 1.9.9` (the default value) :
2843002. Pinkie Pie needs to make another hot fix.
2853013. Pinkie Pie does not want to do a clean up commit like Rainbow Dash.
2863024. Pinkie Pie runs SBT and executes ```> set semVerLimit := 1.4.2``` before any other command.
@@ -289,16 +305,16 @@ change even though only *patch* was required)
289305
290306#### Major Change
291307
292- 1 . Version is ` 1.4.2 ` (from above) and ` semVerLimit := 1.9.9 ` :
308+ 1. Version is `1.4.2` (from above) and `semVerLimit := 1.9.9` (the default value) :
2933092. Rarity wants to make a major breaking API change.
294- 3 . Rarity changes ` semVerLimit := 2.0.0` so she can release ` 2.9.9 ` when she is done .
310+ 3. Rarity changes `gitVersioningSnapshotLowerBound := 2.0.0` which automatically raises default `semVerLimit := 2.9.9`.
2953114. Rarity makes her API change, commits, PRs, and merges.
2963125. Rarity successfully runs the release job for `2.0.0`.
297313
298314#### What should you choose for `semVerLimit`?
299315
300316* First, talk to the team working on the service, or the users of the library. What do they want?
301- * If you want to allow any backward compatible changes might choose a limit like ` semVerLimit := 1.999.999 `
317+ * If you want to allow any backward compatible changes might choose the default limit (e.g. `semVerLimit := 1.999.999`).
302318* If you want to avoid changes you might choose a limit like `semVerLimit := 1.0.999`
303319* If you don' t care about * any* changes you can disable the limt using ` semVerLimit := " " ` .
304320
@@ -310,5 +326,9 @@ Then it uses that artifact as the baseline and compares against your changes.
310326
311327## Notes
312328
313- * [ Semantic versioning] ( http://semver.org/#spec-item-4 ) is disabled for pre-releases (i.e. 0.x.y). You can enable
314- checking if you want by setting ` semVerPreRelease := true `
329+ * [Semantic versioning](http://semver.org/#spec-item-4) is disabled for initial development versions (i.e. 0.x.y).
330+
331+ * When adding a new sub-module within an existing module, be sure to add `semVerEnforceAfterVersion` in the sbt settings
332+ and that version is a minor update.
333+
334+ Example: Current tag is 1.3.4. Then the sbt sub-module settings should have `semvVerEnforceAfterVersion := 1.4.0`
0 commit comments