Gradle Changelog Plugin

This project requires Gradle 6.6 or newer

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

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

Table of contents

• Usage
• Configuration
• Tasks
  • initializeChangelog
  • getChangelog
• Extension Methods
  • get
  • getUnreleased
  • getLatest
  • getAll
  • has
• Changelog.Item
• Gradle Closure in Kotlin DSL
• Helper Methods
• Usage Examples
• Contributing

Usage

Kotlin:

import org.jetbrains.changelog.closure
import org.jetbrains.changelog.date

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

tasks {
    // ...

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

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

Groovy:

import org.jetbrains.changelog.ExtensionsKt

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

apply plugin: 'org.jetbrains.changelog'

intellij {
    // ...

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

changelog {
    version = "1.0.0"
    path = "${project.projectDir}/CHANGELOG.md"
    header = { "[$version] - ${ExtensionsKt.date()}" }
    headerParserRegex = ~/\d+\.\d+/
    itemPrefix = "-"
    keepUnreleasedSection = true
    unreleasedTerm = "[Unreleased]"
    groups = ["Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"]
}

Note: closure is a wrapper for the KotlinClosure0 class and can be used directly as following:

import org.gradle.kotlin.dsl.KotlinClosure0

changeNotes(KotlinClosure0({ changelog.getUnreleased() }))

Configuration

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.

Tasks

The plugin introduces the following tasks:

initializeChangelog

Examples

$ ./gradlew initializeChangelog
$ cat CHANGELOG.md

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

### Changed

### Deprecated

### Removed

### Fixed

### Security

getChangelog

Options

Examples

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

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

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

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

Examples

Kotlin:

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

Groovy:

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

getUnreleased

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

Examples

Kotlin:

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

Groovy:

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

getLatest

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

Examples

Kotlin:

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

Groovy:

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

getAll

The method returns all available Changelog.Item objects.

Examples

Kotlin:

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

Groovy:

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

has

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

Examples

Kotlin:

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

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

Methods

Gradle Closure in Kotlin DSL

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

There is also a neater method available:

import org.jetbrains.changelog.closure

closure { changelog.get("1.0.0") }

Helper Methods

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

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

Contributing

Integration tests

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

settings.gradle:

rootProject.name = "IntelliJ Platform Plugin Template"

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

settings.gradle.kts:

rootProject.name = "IntelliJ Platform Plugin Template"

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