This project requires Gradle 6.7.1 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
  • patchChangelog
• Extension Methods
  • get
  • getOrNull
  • getUnreleased
  • getLatest
  • getAll
  • has
• Changelog.Item
• Helper Methods
• Usage Examples
• Contributing

patchPluginXml task is defined in gradle-intellij-plugin

The latest available version is:

build.gradle.kts (Kotlin)

import org.jetbrains.changelog.date

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

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 '...'
}

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.

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

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

The plugin introduces the following tasks:

Retrieves changelog for the specified version.

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

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

Creates new changelog file with Unreleased section and empty groups.

$ ./gradlew initializeChangelog
$ cat CHANGELOG.md

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

### Changed

### Deprecated

### Removed

### Fixed

### Security

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

$ 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

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.

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.

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() }
    }
}

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

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

build.gradle.kts (Kotlin)

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

build.gradle (Groovy)

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

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

build.gradle.kts (Kotlin)

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

build.gradle (Groovy)

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

The method returns all available Changelog.Item objects.

build.gradle.kts (Kotlin)

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

build.gradle (Groovy)

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

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

build.gradle.kts (Kotlin)

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

build.gradle (Groovy)

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

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:

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')}" }
}

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

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

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

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