Skip to content

spring-io/github-changelog-generator

Repository files navigation

Generate a Changelog for a GitHub Milestone

To generate a markdown changelog that comprise the list of bugs and issues in a GitHub milestone follow these steps:

changelog:
  repository: owner/name
github:
  username:
  password:
Note
When generating a changelog for a public repository, the username and password properties are optional. However, specifying them ensures that you don’t hit GitHub’s rate limit easily.

If you’re using GitHub enterprise, the base url can be set using github.api-url.

Tip
If you are only configuring a few properties you can alternatively use application arguments such as --changelog.repository=…​.
  • Run the following commands:

$ java -jar github-changelog-generator.jar <milestone> <path_to_generate_file>
Note
By default <milestone> refers to the milestone title. If you want to use milestone ID, you should set the changelog.milestone-reference property to id.

Customizing Sections

By default the changelog will contain the following sections:

Title Label Text

":star: New Features"

"enhancement"

":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"]

You can also customize the contributors title using:

changelog:
  contributors:
    title: "Contributors"

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, you can 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 changlog by configuring exclusions. You can ignore all items that have certain labels using changelog.issues.exclude.labeles. 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"

License

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

About

Generates release notes that can be published to GitHub

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Packages

No packages published