@kong/changelog-generator
Advanced tools
Add a line beginning with changelog: to any Pull Requests you would like to be included in the changelog. The remainder of this line will be used to generate a changelog for that Pull Request's changes.
Have a GitHub Auth Token with the public_repo permission. Set this token to the GITHUB_TOKEN environment variable (or pass in with --githubToken <YOUR TOKEN> below). (Note: add a space before export to keep it from being in your terminal history)
export GITHUB_TOKEN=<YOUR TOKEN>
run this (but filling in your own data)
npx @kong/changelog-generator generate --owner Kong --repo insomnia --base v1.1.3 --head v1.1.4 --releaseName "v1.2.0 - Cool New features!"
owner is the GitHub organizationrepo is the GitHub repositorybase is a git ref (in this example, a pre-existing git tag) where the script will start searching, inclusivelyhead is a git ref (in this example, a commit hash) where the script will stop searching, inclusivelyreleaseName is the name of your release, and will appear on the first line of the changelogHere is an example of the generated output.
There are lots of ways to "do" changelogs. The sections that follow outline some of the motivations for the way this script does it.
A good changelog is about clear and effective communication about changes that the changelog's audience will care about. To break that down:
changes does not map directly to PRs or commits. It's sometimes more, and sometimes less than one PR or one commit that constitutes a single change. If we couple one to the other, then we miss important nuiance about what makes for a good changelog.the changelog's audience is not identical to "people developing the project" for almost any changelog. In this way, it makes sense to keep concerns separated.care about is variable, but we can say generally that a general open source contributor is not well prepared to answer this question.You use the script by passing it two git refs. This can be a branch name, a tag, a commit hash, HEAD etc.
This ensures that you can generate the changelog at any moment.
The individual changelog line for an individual piece of work is written at the moment it's freshest in a committer's or reviewer's mind: during the PR review process.
This script generates a changelog for a range of commits.
The main idea behind this script is that it sources information from the pull request.
Q: But what about when there was no pull request, such as an emergency hotfix or something of that sort?
A: There's support for exactly the same functionality as in pull requests if you add your changelog entry to a commit message (in a new line).*
*Note: This is not special-cased for commits without a PR, in fact all commits messages will be searched for a changelog entry. For a given commit, if there is a PR attached and that PR that also has a commit message, the PR will win and the message from the commit will be discarded.
The data is sourced from the PR description because it can be changed later. This is a huge benefit because it means that any contributor will be able to change the changelog entry at any time, including after the PR has merged. This is because contributors on a repo have the ability to update PR descriptions (and, only the descriptions) of all PRs.
If you have a series of 3 PRs that should make just one changelog entry, no problem, just add the changelog to the last one (i.e. the one that completes the project which you want to announce to users in the changelog).
As established above, the changelog is a communication tool between the producers/maintainers of a product and that product's end-users. Open source contributors should not have the responsibility of knowing how the maintainers of a project want to phrase communication with end-users. The contributor's focus should be allowed to stay on the PR. We should not be forcing users to learn our changelog conventions in addition to everything else needed to make their PR.
Simple as that: having a script makes it super easy to add lines like
A big thanks to the 10 contributors who made this release possible. Here are some highlights ✨:
and
All contributors of this release in alphabetical order: @develohpanda, @dimitropoulos, @falondarville, @gatzjames, @jackkav, @JasonCubic, @johnwchadwick, @ttyS0e, @vincendep, @Wils
to the changelogs without any burden of keeping this information "in sync" as the changelog is being written (i.e. forgetting to add up correctly or forgetting to add/thank people).
Some projects do not include employees in "thank you" lists of the sort shown above. One way of looking at it is that doing so would take away from the focus on open source contributors. This script doesn't work this way: it shows gratitude for all contributions equally, regardless of place of employment.
Aside from API calls (such as, to GitHub) to gather information, this script will not push anything anywhere or publish anything. It has the responsibility of generating the changelog and nothing more. If there's more work to do (such as publishing to a website) then do not extend this script, write another script that has that responsibility and call this one as a dependency.
If you have specific questions about the functionality, you should be able to read the tests and view all intended behaviors of the software.
Wanna know if it's case sensitive? Look at the tests.
Wanna see what it would do in a certain scenario? Write a new test.
Tell the script about your GitHub token with the standard GITHUB_TOKEN environment variable, or via the --githubToken command line argument. The token can be generated in your GitHub Token Settings, and needs public_repo permissions.
Run the script (from this package):
yarn start --base core@2021.7.2 --head core@2022.1.0 --releaseName core@2022.1.0
--base is the oldest git ref you'd like the tool to search from, inclusively.--head is the newest git ref you'd like the tool to search to, inclusively.--releaseName will be used in the first line as the name of the release.Do you have this sinking feeling that there's some PR that was simply missed at some stage during review and doesn't have a changelog? Don't worry, this script's got you covered.
Run the same thing as above, but just add --onlyShowMissing, e.g.:
yarn start --base core@2021.7.2 --head core@2022.1.0 --releaseName core@2022.1.0 --onlyShowMissing
Adding that flag will look at the same commits as before, but will instead show you all the commits that do not have a changelog entry. That way, you can click through the PRs and just verify that nothing important was missed.
If you find a PR that was missed, you simply edit the PR description to include a changelog line (like normal) and run the script again. Presto-changeo! All fixed.
This forces a few undesirable things. Say, for example you have a PR that merges with some change
Anyone that has worked on a codebase that does this can probably tell you what a nightmare it can be to hit "Merge" on a PR only to, seconds later, realize there's a typo in the changelog entry that you didn't see until after merging. Then, you'd have to submit a new PR and go through the entire CI/CD process to get that typo fix changed.
Is that more strict? Yes. If you like that kind of approach, this tool is not for you.
This tool tries to find the path of least resistance for generating quality changelogs. Even if you see a problem in the changelog entry in a PR before it merges, you'd still often have to wait through the whole CI process to get that typo changed: even though you know the code hasn't changed.
Just wait a minute or two and try again, it has been our experience that if you quickly run the script in quick succession this can happen, but otherwise it can run once just fine. File a GitHub issue if you still have trouble after waiting.
Admittedly, this is something the script doesn't know much about, but there's an easy way to accomplish it, all the same.
Say your user, @githubuser has two PRs, #1 and #2 that I want to appear on the same changelog line. Edit the PR description of PR #2 to read changelog: some change (#1). That means when the PR is picked up by the script it'll get transformed into - some change (#1) (#2) @githubuser.
If you want to assign different authorship. For example, you can do changelog: some change (#1) @someotheruser which will be transformed into - some change (#1) @someotheruser (#2) @githubuser.
It's a bit of a hack, but it works. If this script becomes more advanced in the future, I'd expect this is something it might start more systematically handling. If you have ideas for how you'd like this to work please feel free to open a GitHub issue.
version field with the version you'd like to releasemain branch with a semver tag beginning with v followed by the version in the package.json, e.g. v0.0.1 and push the tag to originFAQs
a changelog generator focused on flexibility and ease of use
We found that @kong/changelog-generator demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
pnpm 10 blocks lifecycle scripts by default to improve security, addressing supply chain attack risks but sparking debate over compatibility and workflow changes.
Product
Socket now supports uv.lock files to ensure consistent, secure dependency resolution for Python projects and enhance supply chain security.
Research
Security News
Socket researchers have discovered multiple malicious npm packages targeting Solana private keys, abusing Gmail to exfiltrate the data and drain Solana wallets.