Gradle Changelog Plugin

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

Note

This project requires Gradle 6.8 or newer

Upgrade Gradle Wrapper with ./gradlew wrapper --gradle-version 8.3

Table of contents

• Usage
• Configuration
• Tasks
  • getChangelog
  • initializeChangelog
  • patchChangelog
• Extension Methods
  • get
  • getUnreleased
  • getLatest
  • has
  • render
  • renderItem
  • getInstance
• Classes
  • Changelog
  • Changelog.OutputType
  • Changelog.Item
• Helper Methods
• Usage Examples
• Changelog
• Contributing
• License

Usage

The latest available version is:

Note

The patchPluginXml task is defined in Gradle IntelliJ Plugin

build.gradle.kts (Kotlin)

import org.jetbrains.changelog.Changelog
import org.jetbrains.changelog.ChangelogSectionUrlBuilder
import org.jetbrains.changelog.date

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

tasks {
    // ...

    patchPluginXml {
        changeNotes.set(provider {
            changelog.renderItem(
                changelog
                    .getUnreleased()
                    .withHeader(false)
                    .withEmptySections(false),
                Changelog.OutputType.HTML
            )
        })
    }
}

changelog {
    version.set("1.0.0")
    path.set(file("CHANGELOG.md").canonicalPath)
    header.set(provider { "[${version.get()}] - ${date()}" })
    headerParserRegex.set("""(\d+\.\d+)""".toRegex())
    introduction.set(
        """
        My awesome project that provides a lot of useful features, like:
        
        - Feature 1
        - Feature 2
        - and Feature 3
        """.trimIndent()
    )
    itemPrefix.set("-")
    keepUnreleasedSection.set(true)
    unreleasedTerm.set("[Unreleased]")
    groups.set(listOf("Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"))
    lineSeparator.set("\n")
    combinePreReleases.set(true)
    sectionUrlBuilder.set(ChangelogSectionUrlBuilder { repositoryUrl, currentVersion, previousVersion, isUnreleased -> "foo" })
}

build.gradle (Groovy)

import org.jetbrains.changelog.Changelog
import org.jetbrains.changelog.ChangelogSectionUrlBuilder
import org.jetbrains.changelog.ExtensionsKt

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

apply plugin: 'org.jetbrains.changelog'

intellij {
    // ...

    patchPluginXml {
        changeNotes = provider {
            changelog.renderItem(
                changelog
                    .getUnreleased()
                    .withHeader(false)
                    .withEmptySections(false),
                Changelog.OutputType.HTML
            )
        }
    }
}

changelog {
    version = "1.0.0"
    path = file("CHANGELOG.md").canonicalPath
    header = "[${-> version.get()}] - ${ExtensionsKt.date("yyyy-MM-dd")}"
    headerParserRegex = ~/(\d+\.\d+)/
    introduction = """
        My awesome project that provides a lot of useful features, like:
        
        - Feature 1
        - Feature 2
        - and Feature 3
    """.stripIndent()
    itemPrefix = "-"
    keepUnreleasedSection = true
    unreleasedTerm = "[Unreleased]"
    groups = ["Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"]
    lineSeparator = "\n"
    combinePreReleases = true
    sectionUrlBuilder = { repositoryUrl, currentVersion, previousVersion, isUnreleased -> "foo" } as ChangelogSectionUrlBuilder
}

Note

All the extension and task 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
versionPrefix	Version prefix used to compare tags.	Type: String Default value: v
version	Current version. By default, project's version is used.	Type: String Default value: project.version
path	Path to the changelog file.	Type: String Default value: file("CHANGELOG.md").cannonicalPath
preTitle	Optional content placed before the title.	Type: String? Default value: null
title	The changelog title set as the top-lever header – #.	Type: String Default value: "Changelog"
introduction	Optional content placed after the title.	Type: String? Default value: null
header	Header value used when patching the Unreleased section with text containing the current version.	Type: String Default value: provider { "${version.get()} - ${date()}" }
headerParserRegex	Regex/Pattern/String used to extract version from the header string.	Type: Regex / Pattern / String Default value: null, fallbacks to SEM_VER_REGEX
unreleasedTerm	Unreleased section name.	Type: String Default value: "[Unreleased]"
keepUnreleasedSection	Add an unreleased empty section on the top of the changelog after running the patching task.	Type: Boolean Default value: true
patchEmpty	Patches changelog even if no release note is provided.	Type: Boolean Default value: true
groups	List of groups created with a new Unreleased section.	Type: String Default value: ["Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"]
itemPrefix	Single item's prefix, allows to customise the bullet sign.	Type: String Default value: "-"
combinePreReleases	Combines pre-releases (like 1.0.0-alpha, 1.0.0-beta.2) into the final release note when patching.	Type: Boolean Default value: true
lineSeparator	Line separator used for generating changelog content.	Type: String Default value: "\n" or determined from the existing file
repositoryUrl	The GitHub repository URL used to build release links. If provided, leads to the GitHub comparison page.	Type: String? Default value: null
sectionUrlBuilder	Function to build a single URL to link section with the GitHub page to present changes within the given release.	Type: ChangelogSectionUrlBuilder Default value: Common ChangelogSectionUrlBuilder implementation

Note

The 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 a new changelog file with an unreleased section and empty groups.
patchChangelog	Updates the unreleased section to the given version.

getChangelog

Retrieves changelog for the specified version.

Options

Option	Type	Default value	Description
--no-header	Boolean	false	Omits the section header in the changelog output.
--no-summary	Boolean	false	Omits the section summary in the changelog output.
--no-links	Boolean	false	Omits links in the changelog output.
--no-empty-sections	Boolean	false	Omits empty sections in the changelog output.
--project-version	String?	null	Returns change notes for the specified project version.
--unreleased	Boolean	false	Returns change notes for an unreleased section.

Examples

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

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

initializeChangelog

Creates a new changelog file with an 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.

Options

Option	Type	Default value	Description
--release-note	String?	null	Use custom release note to create new changelog entry.

Warning

Content provided with the --release-note option will override the existing release note for the latest unreleased 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

The following methods depend on the changelog extension set in the Configuration build phase. For safe access and process of your changelog file, we recommend accessing the changelog extension within Gradle closures as presented in the Usage section.

changelog.get(version: String): Changelog.Item

The method returns a Changelog.Item? object for the specified version. Throws MissingVersionException if the version is not available.

Parameters

Parameter	Type	Description
version	String	Change note version.

changelog.getUnreleased(): Changelog.Item

The method returns a Changelog.Item object for the unreleased version. Throws MissingVersionException if the version is not available.

changelog.getLatest(): Changelog.Item

The method returns the latest released Changelog.Item object (first on the list). Throws MissingVersionException if the version is not available.

changelog.has(version: String): Boolean

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

Parameters

Parameter	Type	Description
version	String	Change note version.

changelog.render(outputType: Changelog.OutputType): String

Renders the whole Changelog object to string based on the given outputType.

Parameters

Parameter	Type	Description
outputType	Changelog.OutputType	Output type, see Changelog.OutputType

changelog.renderItem(item: Changelog.Item, outputType: Changelog.OutputType): String

Renders the given Changelog.Item object to string based on the given outputType.

Parameters

Parameter	Type	Description
item	Changelog.Item	Item to render, see Changelog.Item
outputType	Changelog.OutputType	Output type, see Changelog.OutputType

changelog.getInstance(): Changelog

Returns the Changelog instance shared among all the tasks. See Changelog for more details.

Classes

Changelog class

The Changelog class is a wrapper for the Changelog file. It provides methods to read and write the changelog file.

Properties

Name	Type	Description
preTitle	String	Optional content placed before the title.
title	String	The changelog title set as the top-lever header – #.
introduction	String	Optional content placed after the title.
items	Map<String, Changelog.Item>	List of all items available in the changelog stored in a map of version to Changelog.Item.
unreleasedItem	Changelog.Item?	An instance of the unreleased item, may be null.
releasedItems	List<Changelog.Item>	List of already released item instances.
links	Map<String, String>	List of all links stored at the end of the changelog in a map of id to url.

Methods

Name	Return type	Description
get(version: String)	Changelog.Item	Returns item for the given version. Throws MissingVersionException if missing.
getLatest()	Changelog.Item	Returns the latest released item. Throws MissingVersionException if missing.
has(version: String)	Boolean	Checks if item with the given version exists.
render(outputType: Changelog.OutputType)	String	Renders the whole Changelog object to string based on the given outputType.
renderItem(item: Changelog.Item, outputType: Changelog.OutputType)	String	Renders the given Changelog.Item object to string based on the given outputType.

Changelog.OutputType enum

Name	Description
MARKDOWN	Default, Markdown content format.
PLAIN_TEXT	Plain text with no Markdown syntax generated.
HTML	HTML content created out of Markdown version.

Changelog.Item class

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	Item version.
header	String	Literal representation of the given item – may contain version with extra meta, like date.
summary	String	Optional summary of the release item.
isUnreleased	Boolean	Determines if an item is released or not.

Methods

Name	Description	Returned type
withHeader(Boolean)	Includes header part in the output.	Changelog.Item
withLinkedHeader(Boolean)	Adds link to the version in the header.	Changelog.Item
withSummary(Boolean)	Includes summary part.	Changelog.Item
withLinks(Boolean)	Returns links used in the release section at the end.	Changelog.Item
withEmptySections(Boolean)	Prints empty sections.	Changelog.Item
withFilter(Boolean)	Applies custom filter to the returned entries.	Changelog.Item
toText()	Deprecated. Use changelog.renderItem(item)	String
toPlainText()	Deprecated. Use changelog.renderItem(item, Changelog.OutputType.PLAIN_TEXT)	String
toString()	Deprecated. Use changelog.renderItem(item, Changelog.OutputType.MARKDOWN)	String
toHTML()	Deprecated. Use changelog.renderItem(item, Changelog.OutputType.HTML)	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, lineSeparator: String = "\n")	Converts given Markdown content to HTML output.	String
markdownToPlainText(input: String, lineSeparator: 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

• IntelliJ Platform Plugin Template
• Gradle IntelliJ Plugin
• Unity Support for ReSharper and Rider

Changelog

All releases are available in the Releases section. The latest available version is:

Contributing

Please see CONTRIBUTING on how to submit feedback and contribute to this project.

License

Licensed under the Apache License, Version 2.0 (the "License"), see LICENCE.