search

spring-io / github-changelog-generator

Generates release notes that can be published to GitHub
Apache License 2.0
109 stars 34 forks source link

readme

= GitHub Changelog Generator

A changelog generator for GitHub Issues, available as a https://github.com/spring-io/github-changelog-generator/releases[release jar] or for use as a GitHub Action.

== Running as a Release Jar

The changelog generator requires Java 17 or later. To generate a markdown changelog using a https://github.com/spring-io/github-changelog-generator/releases[release jar], follow these steps:

To increase https://developer.github.com/v3/?#rate-limiting[GitHub's rate limits], you can also use --github-token=<token> to provide an access token that is used for authentication.

For more advanced configuration options, <<Advanced Configuration,see below>>.

== Using as a GitHub Action

=== Configuration

==== Required Inputs

=== Optional Inputs

=== Minimal Example

[source,yaml,indent=0]

steps:

== Advanced Configuration

A YAML configuration file can be used to provide more complex configuration, either when running as a release jar or as a GitHub action.

=== Customizing Sections

By default, the changelog will contain the following sections:

|=== |Title |Label Text

|":star: New Features" |"enhancement"

|":lady_beetle: Bug Fixes" |"regression" or "bug"

|":notebook_with_decorative_cover: Documentation" |"documentation"

|":hammer: Dependency Upgrades" |"dependency-upgrade" |===

The title is in https://guides.github.com/features/mastering-markdown[Markdown] format and emoji like ":star:" can be used. If you want something different then you can add sections YAML:

[source,yaml]

changelog: sections:

By default, adding sections will replace the default sections. To add sections after the defaults, add the following configuration:

[source, yaml]

changelog: add-sections: true

You can also customize the contributors title using the following:

[source,yaml]

changelog: contributors: title: "Contributors"

You can add external links such as release notes for quick access using the following:

[source,yaml]

changelog: external_links:

==== Showing Issues in Multiple Sections

Unless otherwise configured, issues will only appear in the first matching section. For example, if you have an issue labeled with enhancement and documentation then it will only appear in the "New Features" section.

If you want an issue to appear in multiple sections, use the group property. Groups allow you to create logical groupings of related sections. An issue may only appear once in any given group.

For example, you might define the following:

[source,yaml]

changelog: sections:

This will create two distinct groups, "highlights" and "default" (which is used if no group property is specified). An issue labeled with new and noteworthy will appear in both the "Highlights" and "Enhancements" section.

=== Excluding Issues

Issues and pull requests can be excluded from the changelog by configuring exclusions. You can ignore all items that have certain labels using changelog.issues.exclude.labels. For example:

[source,yaml]

changelog: issues: exclude: labels: ["wontfix", "question", "duplicate", "invalid"]

=== Excluding Contributors

Contributors whose username ends with [bot], such as dependabot[bot] and github-actions[bot], are automatically excluded. If you have other contributors that you want to be excluded (perhaps core team members), you can set the following:

[source,yaml]

changelog: contributors: exclude: names: ["coremember"]

You can also use * if you want to drop the contributors section entirely.

=== Sorting Issues

By default, issues are sorted by their "created" date. If you want to order them by title instead you can set changelog.issues.sort to title. It's also set the property on section configuration if you want ordering per section:

[source,yaml]

changelog: sections:

=== Following Ported Issues

If an issue is forward-ported or backward-ported between milestones, you might have separate issues in each milestone that reference the original issue. To credit a contributor in the changelog for every milestone that includes a forward or backward port of the issue that was resolved, configure the labels that are used to identify ported issues. The body of a ported issue should contain a comment with a reference to the original issue, which is extracted using a regular expression with exactly one capture group for the original issue number.

[source,yaml]

changelog: issues: ports:

=== Disabling Generation of Links to Each Issue

By default, each entry in the changelog will include a link back to the issue or PR on GitHub. The generation of these links can be disabled:

[source,yaml]

changelog: issues: generate_links: false

== License

This project is Open Source software released under the https://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 license].