• Stars
    star
    106
  • Rank 324,851 (Top 7 %)
  • Language
    Java
  • License
    Apache License 2.0
  • Created almost 6 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Generates release notes that can be published to GitHub

GitHub Changelog Generator

A changelog generator for GitHub Issues, available as a 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 release jar, follow these steps:

  • Download a release jar.

  • Run java -jar github-changelog-generator.jar <milestone-title> <changelog-file> --changelog.repository=<org>/<name>

To increase 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, see below.

Using as a GitHub Action

Configuration

Required Inputs

  • milestone: Milestone for which the changelog should be generated

Optional Inputs

  • changelog-file: Path of the file to which the changelog should be written. Defaults to changelog.md

  • config-file: Path to a changelog generator configuration file, relative to GITHUB_WORKSPACE. See below for details of the advanced options that can be configured using this file.

  • repository: Repository for which a changelog should be generated. Defaults to the workflow’s repository.

  • token: Token for authentication with GitHub. Authenticating increases GitHub rate limits.

Minimal Example

steps:
  - name: Generate Changelog
    uses: spring-io/github-changelog-generator@<version-or-sha>
    with:
      milestone: '1.0.0'

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 Markdown format and emoji like ":star:" can be used. If you want something different then you can add sections YAML:

changelog:
  sections:
  - title: "Enhancements"
    labels: ["new"]
  - title: "Bugs"
    labels: ["fix"]

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

changelog:
  add-sections: true

You can also customize the contributors title using the following:

changelog:
  contributors:
    title: "Contributors"

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

changelog:
  external_links:
  - name: "Release Notes"
    location: "https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-2.3-Release-Notes"

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:

changelog:
  sections:
  - title: "Highlights"
    labels: ["noteworthy"]
    group: "highlights"
  - title: "Enhancements"
    labels: ["new"]
  - title: "Bugs"
    labels: ["fix"]

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:

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

Excluding Contributors

If you have contributors that you don’t want to thank (perhaps core team members or bots), you can set the following:

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

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:

changelog:
  sections:
  - title: "Bugs"
    labels: ["bug"]
  - title: "Dependency Upgrades"
    labels: ["dependency"]
    sort: "title"

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.

changelog:
  issues:
    ports:
      - label: "status: forward-port"
        bodyExpression: 'Forward port of issue #(\d+).*'
      - label: "status: backport"
        bodyExpression: 'Back port of issue #(\d+).*'

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:

changelog:
  issues:
    generate_links: false

License

This project is Open Source software released under the Apache 2.0 license.

More Repositories

1

initializr

A quickstart generator for Spring projects
Java
3,409
star
2

start.spring.io

https://start.spring.io
Java
2,182
star
3

spring-javaformat

Java
789
star
4

nohttp

A project for ensuring that https is used
Java
222
star
5

spring-asciidoctor-backends

A backend for Asciidoctor used to produce Spring styled HTML
Java
77
star
6

spring-asciidoctor-extensions

Asciidoctor Extensions developed by the Spring team
Java
45
star
7

spring-doc-resources

Asciidoctor theme for Spring reference documentations
SCSS
40
star
8

dataflow.spring.io

Microsite for Spring Cloud Data Flow
JavaScript
39
star
9

spring-calendar

Java
29
star
10

concourse-java-scripts

Shell
19
star
11

artifactory-resource

Java
18
star
12

antora-ui-spring

CSS
14
star
13

issue-bot

Java
12
star
14

pivotal-cla

Java
10
star
15

develocity-conventions

Java
8
star
16

antora-extensions

Antora extensions developed for the Spring docs.
JavaScript
7
star
17

backport-bot

GitHub Action used to help manage backports
Kotlin
7
star
18

spring-antora-maven-plugins

Antora support for Maven based projects
Java
6
star
19

slackboot

Slack bot names "slackboot" that helps manage guides, etc. from Slack
Java
6
star
20

spring-github-workflows

GitHub Actions Workflows for Spring Projects
6
star
21

homebrew-tap

A brew tap repository for formulae published by spring.io
Ruby
4
star
22

concourse-release-scripts

Promotes and distributes build artifacts using the Artifactory and Bintray APIs
Java
3
star
23

autoln

HTML
3
star
24

spring-io-static

static resources for our CDN
2
star
25

spring-security-release-tools

Libraries and plugins for managing automated releases of Spring projects.
Java
2
star
26

asciidoctor-extensions

Asciidoctor extensions (currently Asciidoctor.js only) developed for the Spring docs.
JavaScript
1
star
27

projects-api

Java
1
star
28

spring-generated-docs

Contains generated materials for Spring Security Antora docs
1
star
29

spring-gradle-build-action

Reusable GitHub Action for performing a gradle build or running a gradle task.
Shell
1
star
30

cve-2022-22976-bcrypt-skips-salt

Java
1
star
31

google-chat-notify-resource

Java
1
star
32

spring-io.github.io

1
star
33

antora-xref-extension

JavaScript
1
star
34

nexus-sync-action

TypeScript
1
star