• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    迪恩网络公众号

JetBrains/gradle-changelog-plugin: Plugin for parsing and managing the Changelog ...

原作者: [db:作者] 来自: 网络 收藏 邀请

开源软件名称(OpenSource Name):

JetBrains/gradle-changelog-plugin

开源软件地址(OpenSource Url):

https://github.com/JetBrains/gradle-changelog-plugin

开源编程语言(OpenSource Language):

Kotlin 100.0%

开源软件介绍(OpenSource Introduction):

Gradle Changelog Plugin

official JetBrains project Twitter Follow Gradle Plugin Build Slack

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.

Table of contents

Usage

patchPluginXml task is defined in gradle-intellij-plugin

The latest available version is: Gradle Plugin

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.

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

Changelog

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

Gradle Plugin

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.




鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
热门推荐
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap