Gradle Changelog Plugin

This project requires Gradle 6.6 or newer

TIP: Upgrade Gradle Wrapper with ./gradlew wrapper --gradle-version 7.4.2

A Gradle plugin providing tasks and helper methods to simplify working with a changelog that is managed in the keep a changelog style.

Usage
Configuration
Tasks
- initializeChangelog
- getChangelog
Extension Methods
- get
- getOrNull
- getUnreleased
- getLatest
- getAll
- has
Changelog.Item
Helper Methods
Usage Examples
Contributing

Usage

patchPluginXml task is defined in gradle-intellij-plugin

build.gradle.kts (Kotlin)

import org.jetbrains.changelog.date

plugins {
    id("org.jetbrains.changelog") version "1.3.1"
}

tasks {
    // ...

    patchPluginXml {
        changeNotes(provider { changelog.getUnreleased().toHTML() })
    }
}

changelog {
    version.set("1.0.0")
    path.set("${project.projectDir}/CHANGELOG.md")
    header.set(provider { "[${version.get()}] - ${date()}" })
    itemPrefix.set("-")
    keepUnreleasedSection.set(true)
    unreleasedTerm.set("[Unreleased]")
    groups.set(listOf("Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"))
}

build.gradle (Groovy)

import java.text.SimpleDateFormat
import org.jetbrains.changelog.ExtensionsKt

plugins {
    id 'org.jetbrains.changelog' version '1.3.1'
}

apply plugin: 'org.jetbrains.changelog'

intellij {
    // ...

    patchPluginXml {
        changeNotes({ changelog.getUnreleased().toHTML() })
    }
}

changelog {
    version = "1.0.0"
    path = "${project.projectDir}/CHANGELOG.md"
    header = "[${-> version.get()}] - ${new SimpleDateFormat("yyyy-MM-dd").format(new Date())}"
    headerParserRegex = ~/(\d+\.\d+)/
    itemPrefix = "-"
    keepUnreleasedSection = true
    unreleasedTerm = "[Unreleased]"
    groups = ["Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"]
}

Note: All the extension and tasks properties are now lazy (see Lazy Configuration).

To set values in Kotlin DSL, use .set(...) method explicitly, like changelog.version.set("1.0.0"), in Groovy it is still possible to use = assignment.

To access property value, call .get(), like: changelog.version.get() in both variants.

Configuration

Plugin can be configured with the following properties set in the changelog {} closure:

Property	Description	Default value
`version`	Current version. By default, global project's version is used.	`project.version`
`groups`	List of groups created with a new Unreleased section.	`["Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"]`
`header`	`String` or `Provider` that returns current header value.	`provider { "[${version.get()}]" }`
`headerParserRegex`	`Regex`/`Pattern`/`String` used to extract version from the header string.	`null`, fallbacks to `ChangelogPluginConstants#SEM_VER_REGEX`
`itemPrefix`	Single item's prefix, allows to customise the bullet sign.	`"-"`
`keepUnreleasedSection`	Add Unreleased empty section after patching.	`true`
`patchEmpty`	Patches changelog even if no release note is provided.	`true`
`path`	Path to the changelog file.	`"${project.projectDir}/CHANGELOG.md"`
`unreleasedTerm`	Unreleased section text.	`"[Unreleased]"`

Note: header closure has the delegate explicitly set to the extension's context for the sake of the Configuration cache support.

Tasks

The plugin introduces the following tasks:

Task	Description
`getChangelog`	Retrieves changelog for the specified version.
`initializeChangelog`	Creates new changelog file with Unreleased section and empty groups.
`patchChangelog`	Updates the unreleased section to the given version. Requires unreleased section to be present in the changelog file.

`getChangelog`

Retrieves changelog for the specified version.

Options

Option	Description
`--no-header`	Skips the first version header line in the output.
`--unreleased`	Returns Unreleased change notes.

Examples

$ ./gradlew getChangelog --console=plain -q --no-header

### Added
- Initial project scaffold
- GitHub Actions to automate testing and deployment
- Kotlin support

`initializeChangelog`

Creates new changelog file with Unreleased section and empty groups.

Examples

$ ./gradlew initializeChangelog
$ cat CHANGELOG.md

## [Unreleased]
### Added
- Example item

### Changed

### Deprecated

### Removed

### Fixed

### Security

`patchChangelog`

Updates the unreleased section to the given version. Requires unreleased section to be present in the changelog file.

Options

Option	Description
`--release-note`	Adds custom release note to the latest changelog entry.

Examples

$ cat CHANGELOG.md
## [Unreleased]
### Added
- A based new feature
 
$ ./gradlew patchChangelog
$ cat CHANGELOG.md

## [Unreleased]
### Added

## [1.0.0]
### Added
- A based new feature

$ cat CHANGELOG.md
## [Unreleased]
### Added
- This note will get overridden by the `--release-note`

$ ./gradlew patchChangelog --release-note='- Foo'
$ cat CHANGELOG.md
## [Unreleased]
### Added

## [1.0.0]
- Foo

Extension Methods

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 run properly, it's required to place the configuration before the first usage of such a method. Alternatively, you can pass the Gradle closure to the task, which will postpone the method invocation.

`get`

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.

Parameters

Parameter	Type	Description	Default value
`version`	`String`	Change note version.	`${changelog.version}`

Examples

build.gradle.kts (Kotlin)

tasks {
    patchPluginXml {
        changeNotes.set(provider { changelog.get("1.0.0").toHTML() })
    }
}

build.gradle (Groovy)

tasks {
    patchPluginXml {
        changeNotes = { changelog.get("1.0.0").toHTML() }
    }
}

`getOrNull`

Same as get, but returns null instead of throwing MissingVersionException.

Parameters

Parameter	Type	Description	Default value
`version`	`String`	Change note version.	`${changelog.version}`

`getUnreleased`

The method returns a Changelog.Item object for the unreleased version.

Examples

build.gradle.kts (Kotlin)

tasks {
    patchPluginXml {
        changeNotes.set(provider { changelog.getUnreleased().toHTML() })
    }
}

build.gradle (Groovy)

tasks {
    patchPluginXml {
        changeNotes = { changelog.getUnreleased().toHTML() }
    }
}

`getLatest`

The method returns the latest Changelog.Item object (first on the list).

Examples

build.gradle.kts (Kotlin)

tasks {
    patchPluginXml {
        changeNotes.set(provider { changelog.getLatest().toHTML() })
    }
}

build.gradle (Groovy)

tasks {
    patchPluginXml {
        changeNotes = { changelog.getLatest().toHTML() }
    }
}

`getAll`

The method returns all available Changelog.Item objects.

Examples

build.gradle.kts (Kotlin)

extension.getAll().values.map { it.toText() }

build.gradle (Groovy)

extension.getAll().values().each { it.toText() }

`has`

The method checks if the given version exists in the changelog.

Examples

build.gradle.kts (Kotlin)

tasks {
    patchPluginXml {
        provider { changelog.has("1.0.0") }
    }
}

build.gradle (Groovy)

tasks {
    patchPluginXml {
        { changelog.has("1.0.0") }
    }
}

`Changelog.Item`

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:

Properties

Name	Type	Description
`version`	`String`	Change note version.

Methods

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`

Helper Methods

Name	Description	Returned type
`date(pattern: String = "yyyy-MM-dd")`	Shorthand for retrieving the current date in the given format.	`String`
`markdownToHTML(input: String)`	Converts given Markdown content to HTML output.	`String`
`markdownToPlainText(input: String)`	Converts given Markdown content to Plain Text output.	`String`

Note: To use package-level Kotlin functions in Groovy, you need to import the containing file as a class:
import org.jetbrains.changelog.ExtensionsKt

changelog {
  header = { "[$version] - ${ExtensionsKt.date('yyyy-MM-dd')}" }
}

Usage Examples

Contributing

Integration tests

To perform integration tests with an existing project, bind the gradle-changelog-plugin sources in the Gradle settings file:

settings.gradle.kts (Kotlin)

rootProject.name = "<Project Name>"

includeBuild("/Users/hsz/Projects/JetBrains/gradle-changelog-plugin")

settings.gradle (Groovy)

rootProject.name = "<Project Name>"

includeBuild '/Users/hsz/Projects/JetBrains/gradle-changelog-plugin'

wonghsin / gradle-changelog-plugin

Gradle Changelog Plugin

Table of contents

Usage

Configuration

Tasks

`getChangelog`

Options

Examples

`initializeChangelog`

Examples

`patchChangelog`

Options

Examples

Extension Methods

`get`

Parameters

Examples

`getOrNull`

Parameters

`getUnreleased`

Examples

`getLatest`

Examples

`getAll`

Examples

`has`

Examples

`Changelog.Item`

Properties

Methods

Helper Methods

Usage Examples

Contributing

Integration tests

About

Languages