Branch | Travis CI | CodeFactor | Codacy | Better Code Hub |
---|---|---|---|---|
Master | ||||
Develop |
Plugin Version | SBT Version | sbt-release Version | sbt-mdoc Version |
---|---|---|---|
0.x.x | 1.x.x | 1.x.x | 1.x.x |
1.x.x | 1.x.x | 1.x.x | 2.x.x |
This plugin modifies sbt-release's releaseProcess
SettingKey
to execute sbt-mdoc's mdoc
InputTask
and commit the changes during release.
The new release process is based on sbt-release
's default Release Process (https://github.com/sbt/sbt-release#user-content-release-process, https://github.com/sbt/sbt-release#user-content-the-default-release-process), with 2 new steps:
- Check that the working directory is a git repository and the repository has no outstanding changes. Also prints the hash of the last commit to the console.
- If there are any snapshot dependencies, ask the user whether to continue or not (default: no).
- Ask the user for the
release version
and thenext development version
. Sensible defaults are provided. - run
clean
- Run
test:test
, if any test fails, the release process is aborted. - Write
version in ThisBuild := "$releaseVersion"
to the fileversion.sbt
and also apply this setting to the current build state. - Commit the changes in
version.sbt
. - Run
mdoc
. - Commit the
mdoc
output files. - Tag the previous commit with
v$version
(eg.v1.2
,v1.2.3
). - Run
publish
. - Write
version in ThisBuild := "nextVersion"
to the fileversion.sbt
and also apply this setting to the current build state. - Commit the changes in
version.sbt
.
specifically:
import ReleaseStateTransformations._
releaseProcess := Seq[ReleaseStep](
checkSnapshotDependencies,
inquireVersions,
runClean,
runTest,
setReleaseVersion,
commitReleaseVersion,
ReleasePlugin.autoImport.releaseStepInputTask(MdocPlugin.autoImport.mdoc),
ReleaseMdocStateTransformations.commitMdoc,
tagRelease,
publishArtifacts,
setNextVersion,
commitNextVersion,
pushChanges
)
Add the following to your project/plugins.sbt
:
addSbtPlugin("com.github.daniel-shuy" % "sbt-release-mdoc" % "1.0.1")
Override the sbt-mdoc
and mdoc
dependency versions with the version of mdoc you wish to use:
addSbtPlugin("com.github.daniel-shuy" % "sbt-release-mdoc" % "1.0.1")
val mdocVersion = "2.0.0"
addSbtPlugin("org.scalameta" % "sbt-mdoc" % mdocVersion)
libraryDependencies ++= Seq(
"org.scalameta" %% "mdoc" % mdocVersion
)
// build.sbt
lazy val root = (project in file("."))
.enablePlugins(MdocPlugin)
.settings(
// ...
)
See https://scalameta.org/mdoc/docs/installation.html#reference for the full documentation on sbt-mdoc
settings.
Minimal Example to substitute @VERSION@
placeholders with project version
and generate markdown files in project base directory:
// docs/README.md
version = @VERSION@
// build.sbt
lazy val root = (project in file("."))
.enablePlugins(MdocPlugin)
.settings(
mdocOut := baseDirectory.in(ThisBuild).value,
mdocVariables := Map(
"VERSION" -> version.value
),
)
Setting | Type | Description |
---|---|---|
releaseMdocCommitMessage | String | Optional. The commit message to use when committing mdoc output files. |
- This project now uses itself to generate this
README
!
If you need to customize sbt-release
's releaseProcess
, use ReleasePlugin.autoImport.releaseStepInputTask(MdocPlugin.autoImport.mdoc)
and ReleaseMdocStateTransformations.commitMdoc
to add the ReleaseStep
s to your build.
When releasing in a CI tool, set releaseMdocCommitMessage
to modify the commit message to skip building (else your build may recurse infinitely).
Example for Travis CI:
// build.sbt
lazy val root = (project in file("."))
.enablePlugins(MdocPlugin)
.settings(
releaseMdocCommitMessage := s"[ci skip] ${releaseMdocCommitMessage.value}"
)
Because Mdoc can only import from dependencies that are available at runtime, if you need to import a provided
/test
dependency or a dependency that your project doesn't already depend on, separate the Mdoc project and add them to libraryDependencies
.
import ReleaseTransformations._
lazy val root = project
.in(file("."))
.settings(
skip in publish := true,
releaseProcess := Seq[ReleaseStep](
checkSnapshotDependencies,
inquireVersions,
),
releaseProcess ++= releaseStepScopedReleaseAndRemaining(myproject).toSeq,
releaseProcess ++= Seq[ReleaseStep](
setReleaseVersion,
commitReleaseVersion,
),
releaseProcess ++= releaseStepScopedReleaseAndRemaining(docs).toSeq,
releaseProcess ++= Seq[ReleaseStep](
tagRelease,
publishArtifacts,
setNextVersion,
commitNextVersion,
pushChanges,
),
)
.aggregate(myproject, docs)
lazy val myproject = project // your existing library
.settings(
// ...
releaseProcess := Seq[ReleaseStep](
runClean,
runTest,
),
// ...
)
lazy val docs = project
.in(file("myproject-docs"))
.settings(
skip in publish := true,
libraryDependencies ++= Seq(
// declare additional dependencies here
),
releaseProcess := Seq[ReleaseStep](
ReleasePlugin.autoImport.releaseStepInputTask(MdocPlugin.autoImport.mdoc),
ReleaseMdocStateTransformations.commitMdoc,
),
)
.dependsOn(myproject)
.enablePlugins(MdocPlugin)