This project requires Gradle 5.0 or newer
A Gradle plugin that provides tasks and helper methods to let the working with the changelog managed in a keep a changelog style easier.
Kotlin:
import org.jetbrains.changelog.closure
plugins {
id("org.jetbrains.changelog") version "0.3.2"
}
tasks {
// ...
patchPluginXml {
changeNotes(closure { changelog.getUnreleased().noHeader().toHTML() })
}
}
changelog {
version = "${project.version}"
path = "${project.projectDir}/CHANGELOG.md"
headerFormat = "[{0}]"
headerArguments = listOf("${project.version}")
itemPrefix = "-"
keepUnreleasedSection = true
unreleasedTerm = "Unreleased"
}
Groovy:
plugins {
id 'org.jetbrains.changelog' version '0.3.2'
}
apply plugin: 'org.jetbrains.changelog'
intellij {
// ...
patchPluginXml {
changeNotes({ changelog.getUnreleased().noHeader().toHTML() })
}
}
changelog {
version = "${project.version}"
path = "${project.projectDir}/CHANGELOG.md"
headerFormat = "[{0}]"
headerArguments = ["${project.version}"]
itemPrefix = "-"
keepUnreleasedSection = true
unreleasedTerm = "Unreleased"
}
Note:
closure
is a wrapper for theKotlinClosure0
class and can be used directly as following:import org.gradle.kotlin.dsl.KotlinClosure0 changeNotes(KotlinClosure0({ changelog.getUnreleased() }))
Plugin can be configured with the following properties set in the changelog {}
closure:
Property | Description | Default value |
---|---|---|
version |
Current project's version. | "${project.version}" |
path |
Path to the changelog file. | "${project.projectDir}/CHANGELOG.md" |
headerFormat |
Format of the version section header. | "[{0}]" |
headerArguments |
Arguments passed to the header by the patchChangelog task. | ["${project.version}"] |
itemPrefix |
Single item's prefix, allows to customise the bullet sign. | "-" |
keepUnreleasedSection |
Add Unreleased empty section after patching. | true |
unreleasedTerm |
Unreleased section text. | "Unreleased" |
The plugin introduces the following tasks:
Task | Description |
---|---|
getChangelog |
Retrieves changelog for the specified version. |
patchChangelog |
Updates the unreleased section to the given version. |
Option | Description |
---|---|
--no-header |
Skips the first version header line in the output. |
--unreleased |
Returns Unreleased change notes. |
$ ./gradlew getChangelog --no-daemon --console=plain -q --no-header
### Added
- Initial project scaffold
- GitHub Actions to automate testing and deployment
- Kotlin support
All the methods are available via the changelog
extension and allow for reading the changelog file within
the Gradle tasks to provide the latest (or specific) change notes.
Note: Following methods depend on the
changelog
extension, which is set in the Configuration build phase. To make it running properly, it's required to place the configuration before the fist usage of such a method. Alternatively, you can pass the Gradle closure to the task, which will postpone the method invocation.
The method returns a Changelog.Item
object for the specified version.
Throws MissingVersionException
if the version is not available.
It is possible to specify the unreleased section with setting the ${changelog.unreleasedTerm}
value.
Parameter | Type | Description | Default value |
---|---|---|---|
version |
String |
Change note version. | ${changelog.version} |
Kotlin:
tasks {
patchPluginXml {
changeNotes(closure { changelog.get("1.0.0").noHeader().toHTML() })
}
}
Groovy:
tasks {
patchPluginXml {
changeNotes({ changelog.get("1.0.0").noHeader().toHTML() })
}
}
The method returns a Changelog.Item
object for the unreleased version.
Kotlin:
tasks {
patchPluginXml {
changeNotes(closure { changelog.getUnreleased().toHTML() })
}
}
Groovy:
tasks {
patchPluginXml {
changeNotes({ changelog.getUnreleased().toHTML() })
}
}
The method returns the latest Changelog.Item
object (first on the list).
Kotlin:
tasks {
patchPluginXml {
changeNotes(closure { changelog.getLatest().toHTML() })
}
}
Groovy:
tasks {
patchPluginXml {
changeNotes({ changelog.getLatest().toHTML() })
}
}
The method checks if the giver version exists in the changelog
Kotlin:
tasks {
patchPluginXml {
closure { changelog.hasVersion() }
}
}
Groovy:
tasks {
patchPluginXml {
{ changelog.hasVersion() }
}
}
Methods described in the above section return Changelog.Item
object, which is a representation of the single
changelog section for the specific version. It provides a couple of properties and methods that allow altering
the output form of the change notes:
Name | Type | Description |
---|---|---|
version |
String |
Change note version. |
Name | Description | Returned type |
---|---|---|
noHeader() |
Excludes header part. | this |
noHeader(Boolean) |
Includes/excludes header part. | this |
getHeader() |
Returns header text. | String |
toText() |
Generates Markdown output. | String |
toPlainText() |
Generates Plain Text output. | String |
toString() |
Generates Markdown output. | String |
toHTML() |
Generates HTML output. | String |
To produce Gradle-specific closure in Kotlin DSL, required by some third-party plugins, like
gradle-intellij-plugin it is required to wrap the Kotlin Unit with KotlinClosure0
class:
KotlinClosure0({ changelog.get() })
There is also a neater method available:
import org.jetbrains.changelog.closure
closure { changelog.get() }