lerna / lerna-changelog

:book: PR-based changelog generator with monorepo support

lerna-changelog

PR-based changelog generator with monorepo support

Usage

npx lerna-changelog

## Unreleased (2018-05-24)

#### :bug: Bug Fix
* [#198](https://github.com/my-org/my-repo/pull/198) Avoid an infinite loop ([@helpful-hacker](https://github.com/helpful-hacker))

#### :house: Internal
* [#183](https://github.com/my-org/my-repo/pull/183) Standardize error messages ([@careful-coder](https://github.com/careful-coder))

#### Commiters: 2
- Helpful Hacker ([@helpful-hacker](https://github.com/helpful-hacker))
- [@careful-coder](https://github.com/careful-coder)

By default lerna-changelog will show all pull requests that have been merged since the latest tagged commit in the repository. That is however only true for pull requests with certain labels applied. The labels that are supported by default are:

• breaking (:boom: Breaking Change)
• enhancement (:rocket: Enhancement)
• bug (:bug: Bug Fix)
• documentation (:memo: Documentation)
• internal (:house: Internal)

You can also use the --from and --to options to view a different range of pull requests:

npx lerna-changelog --from=v1.0.0 --to=v2.0.0

Monorepo support

If you have a packages folder and your projects in subfolders of that folder lerna-changelog will detect it and include the package names in the changelog for the relevant changes.

GitHub Token

Since lerna-changelog interacts with the GitHub API you may run into rate limiting issues which can be resolved by supplying a "personal access token":

export GITHUB_AUTH="..."

You'll need a personal access token for the GitHub API with the repo scope for private repositories or just public_repo scope for public repositories.

Configuration

You can configure lerna-changelog in various ways. The easiest way is by adding a changelog key to the package.json file of your project:

{
  // ...
  "changelog": {
    "labels": {
      "feature": "New Feature",
      "bug": "Bug Fix"
    }
  }
}

The supported options are:

• repo: Your "org/repo" on GitHub (automatically inferred from the package.json file)

• nextVersion: Title for unreleased commits (e.g. Unreleased)

• labels: GitHub PR labels mapped to changelog section headers

• ignoreCommitters: List of committers to ignore (exact or partial match). Useful for example to ignore commits from bots.

• cacheDir: Path to a GitHub API response cache to avoid throttling (e.g. .changelog)

License

lerna-changelog is released under the MIT License.

lerna-changelog's Issues

Support organization PRs

Imagine that user foo opens a PR to lerna/lerna-changelog pointing to a branch in bar/lerna-changelog with bar being a GitHub organization. It might make sense to include the link to bar in the changelog next to the link to foo unless the org equals the org of the repo itself (bar === lerna in this case).

Example

• #60 Add support for homu merge commits. (@Turbo87 / @ember-cli)

Add option to print last version changes

It's currently possible to get all the changes since the last release by running lerna-changelog before you publish a new release. This spits out a list of changes with a ## Unreleased (2016-05-24) title.

It would be great to have similar behaviour made available after you publish a new release, so that instead of ## Unreleased (2016-05-24) you get ## v1.2.3 (2016-05-24).

I realize this is currently possible with the --tag-from and --tag-to options, e.g. lerna-changelog --tag-from=v1.2.2 --tag-to=v1.2.3, but you need to specify tags explicitly.

It would be great to have a flag like --tag-latest that spits out the last release changes.

Skip changes to files in `publishConfig.ignore`

Don't need to include README changes, etc.

Fix single repo changelog

Should just remove the Other packages category if only 1 package (https://github.com/babel/babylon/)

Still getting an empty changelog

Hello,

I follow the instructions on the readme but when I run the changelog generator I only get an empty changelog. I'm missing any configuration? Maybe I should specify a commit to start from? My repository was not managed by lerna from the beginning, but from specific point in the time. Could this be the problem?

Regards

Add default set of labels

IMHO we should use the default labels that GitHub uses as a default in the changelog generator instead of doing essentially nothing if no labels/categories are defined.

new version ?

hey, any exception when a new version will be released to NPM?

Default `repo`

Auto-detect from git remote -v?

Suggested by @hzoo.

Committers with no name on github show up as `null`

#### Commiters: 4
- Bo Borgerson ([gigabo](https://github.com/gigabo))
- Douglas Wade ([doug-wade](https://github.com/doug-wade))
- Sasha Aickin ([aickin](https://github.com/aickin))
- null ([roblg](https://github.com/roblg))

Provide inline example config when missing config

Nicer than just linking to the online docs on github.

Able to group changes per tag

Currently, if I run this command

GITHUB_AUTH= lerna-changelog --tag-from v0.0.1

It will combine all PRs into the latest release.
Example current version is v0.0.9, it will combine all PRs between v0.0.1 to 0.0.9 into v0.0.9's changelog.

If we can group them into tags like

v0.0.1
  release 1
  release 2
v0.0.2
  release 3
...
v0.0.9
  release xx

We can do generate CHANGELOG automatically via CI.

Omit changes from private packages

Seems like if the changes aren't public they don't need to be highlighted in the changelog.

Does this make sense?

Support scoped packages

In https://github.com/glimmerjs/glimmer.js we have

/
+- packages
   +- @glimmer
      +- foo
      +- bar
      +- baz

but the package names are all resolved as @glimmer instead of using the full package name.

We should either look at the individual package.json files or have a special code path if the first character of the subfolder of packages is an @.

lerna-changelog as part of lerna publish

Hey,

Is there any best practice for how to integrate both?
atm, lerna-changelog only spits to screen the unreleased changes,
but i want it to actually update CHANGELOG.md automatically when i use lerna publish..

Cannot read map of undefined when running lerna-changelog

Not sure what is is happening, but when I run lerna-changelog I get the below errors.
I'm on windows git-bash shell.

Regards

C:\Users\rdani\AppData\Roaming\npm\node_modules\lerna-changelog\cli.js:15
    throw (e);
    ^

TypeError: Cannot read property 'map' of undefined
    at C:\Users\rdani\AppData\Roaming\npm\node_modules\lerna-changelog\lib\Changelog.js:232:34
    at Array.forEach (native)
    at C:\Users\rdani\AppData\Roaming\npm\node_modules\lerna-changelog\lib\Changelog.js:231:14
    at Array.map (native)
    at Changelog.getCommitsByCategory (C:\Users\rdani\AppData\Roaming\npm\node_modules\lerna-changelog\lib\Changelog.js:228:48)
    at Changelog.createMarkdown (C:\Users\rdani\AppData\Roaming\npm\node_modules\lerna-changelog\lib\Changelog.js:63:36)
    at Object.<anonymous> (C:\Users\rdani\AppData\Roaming\npm\node_modules\lerna-changelog\cli.js:10:33)
    at Module._compile (module.js:570:32)
    at Object.Module._extensions..js (module.js:579:10)

Generate a changelog entry for a previous release

Currently just does everything since last tag and labels "Unreleased". Would be nice to be able to backfill by specifying previous release tags. Maybe with a --release <tag> option?

PR Stats

Maybe this doesn't have to be part of a changelog but who knows?

• Time to close the issue/time to merge a PR
• special note if its a contributors first PR
• etc

Generic git repo support

Any plans of making the "repo" param take a generic git url, rather than a GH repo name.

For example:

"repo": "[email protected]:owner/repo.git"

Have a way to support commits without prs

might be necessary?

Or we add a message about this in the readme

Unable to get output to render

Hi -

I globally installed lerna-changelog:

I setup my config:

{
  "lerna": "2.0.0",
  "version": "0.7.0",
  "ignoreCommitters": false,
  "changelog": {
    "repo": "clearcapital/ccp",
    "labels": {
      "feature": ":rocket: New Feature",
      "bug": ":bug: Bug Fix"
    },
    "cacheDir": ".changelog"
  }
}

I verified that I am using correct labels for labels in my repo.

I created my GitHub API access token selecting the repo option as I have a private repo. I used that key to authenticate.

When I run lerna-changelog:

The cacheDir at my application root is created but nothing to 'CopyPasta' in the console. I feel like I am missing something really dumb here.

How do I get the output to copy into a changelog.md file?

Thanks!.

Jordan

Issue linking doesn't catch "closes <ticket>" messages

Should support the whole set of keywords for closing issues.

Add changelog to github releases/others?

Curious to see if you can do that automatically as well

like in https://github.com/lerna/lerna-changelog/releases

Document monorepo support

I was looking for something to handle changelogs in monorepos and I came across this. The description of this repo is:

PR-based changelog generator with monorepo support

However nowhere in the readme is it described in what way monorepos are supported so I'm not sure why I would use this instead of something else for my monorepos. Perhaps the monorepo support could be described a bit more in the readme?

Doesn't work well with independent mode

Example below

Since each thing is independent it doesn't make sense to have a changelog entry per release since each one is seperate.

---

Changelog for 2016-08-31

Bug Fix

• babel-preset-babili
  • #135 update older packages. (@hzoo)
  • #125 Revert "Throw upgrade error when babel version is less than 6.14.0". (@kangax)
  • #116 Throw upgrade error when babel version is less than 6.14.0. (@boopathi)
• babili
  • #128 add --no-babelrc option. (@hzoo)
• babel-plugin-minify-mangle-names, babel-preset-babili
  • #123 Add fix for other types of nodes in referencePaths. (@boopathi)
• babel-plugin-minify-simplify
  • #119 Fix bug - Conditionals transformation for impure paths. (@boopathi)

The 'repo' field automatically inferred failed, but no error occurred

Refer to Configuration section:

repo: Your "org/repo" on GitHub (automatically inferred)

I didn't specify a 'repo' field, then ran global installed lerna-changelog, and nothing happened, no CHANGELOG or ERROR

Dived into source and got a 'https://api.github.com/repos/undefined/issues/2'. Set a 'repo' field then it works well.

So, an ERROR message is required as it can't be inferred automatically.

Some tests would be nice

What's the right granularity? Could go nearly end-to-end and set up a whole lerna repo with commit history. Alternatively could try to pull out just the content generation and test that.

What Github scopes should the access token have?

The Readme says I need to create a personal access token. What scopes should it have? I assume repo ?

Problem when referenced issue is not found

I'm facing some issues while testing your lib. In the line referenced, you try to map the issues labels.
For some reasons I get in the github response

{ 
    "commitSHA":"xxxxxx",
    "message":"Merge pull request #838 from xxxx/dev",
    "tags":["vxxxx"],
    "issueNumber":"838",
    "date":"2017-09-14",
    "githubIssue":{
        "message":"Not Found",
        "documentation_url":"https://developer.github.com/v3"
    }
}

lerna-changelog/src/changelog.ts

Line 195 in a413287

const labels = commit.githubIssue.labels.map((label) => label.name.toLowerCase());

Sort tags by semver

Currently the tags seem to rely on Object.keys() sorting behavior... 🤔

Support for repos hosted on gitlab

Not all projects are hosted on GitHub. A good second host might be gitlab.

Explain how changelog is generated on Readme

Hello,

Understanding how the changelog is generated would help users understand why they are getting the results they saw and how they can improve their workflow to take maximum advantage of lerna-changelog.

For example, I'm getting the following output:

## Unreleased (2017-01-04)

#### Committers: 0

And I can't understand why. Having at least a friendly explanation of how changes are fetched would help a lot.

Regards

Remove trailing whitespace from output when there are no changes

Currently, if there are no labeled PRs since the last commit, lerna-changelog will output 3 lines of whitespace

➜  as24-custom-events git:(changelog_generation) ✗ npx lerna-changelog


➜  as24-custom-events git:(changelog_generation) ✗

this makes it annoying when we want to automate updating the CHANGELOG automatically via CI because the file will grow even if there are no changes. Should be simple enough to run a .trim to the output

Better behavior when missing configuration

Just accidentally ran lerna-changelog on a branch that didn't have changelog config in lerna.json yet.

It throws an unhelpful error: TypeError: Cannot set property 'rootPath' of undefined.

Should throw a ConfigurationError with setup instructions. Maybe point to README?

Readme lacking how it takes PRs -> Changelog

Looking at the readme I'm still not sure how this takes a set of PR's or commits and generates a list.

Would be insanely helpful to show an example PR message and highlight how and why that ends up in the change log.

Support a wildcard/"other" label

It might make sense in some projects to also include all the PRs in the changelog that don't have matching labels on them. We should probably support some sort of wildcard that groups all the PRs under it that don't have any of the other labels on them.

Error when running `lerna-changelog` in narrow terminal

Running lerna-changelog in a terminal with only 51 (or fewer) character width throws an error:

❯ lerna-changelog
RangeError: Invalid array length
    at ProgressBar.render (/Users/rjackson/src/open-source/ember-cli-babel/node_modules/progress/lib/node-progress.js:132:16)
    at ProgressBar.tick (/Users/rjackson/src/open-source/ember-cli-babel/node_modules/progress/lib/node-progress.js:86:8)
    at ProgressBarController.setTitle (/Users/rjackson/src/open-source/ember-cli-babel/node_modules/lerna-changelog/lib/progress-bar.js:26:22)
    at Changelog.<anonymous> (/Users/rjackson/src/open-source/ember-cli-babel/node_modules/lerna-changelog/lib/changelog.js:231:68)
    at step (/Users/rjackson/src/open-source/ember-cli-babel/node_modules/lerna-changelog/lib/changelog.js:32:23)
    at Object.next (/Users/rjackson/src/open-source/ember-cli-babel/node_modules/lerna-changelog/lib/changelog.js:13:53)
    at /Users/rjackson/src/open-source/ember-cli-babel/node_modules/lerna-changelog/lib/changelog.js:7:71
    at Promise (<anonymous>)
    at __awaiter (/Users/rjackson/src/open-source/ember-cli-babel/node_modules/lerna-changelog/lib/changelog.js:3:12)
    at pMap.concurrency (/Users/rjackson/src/open-source/ember-cli-babel/node_modules/lerna-changelog/lib/changelog.js:226:85)

Use real names in "committers" section

Github usernames are great, but acknowledging contributors by name would be nice.

For example:

#### Commiters: 3
- Douglas Wade [doug-wade](https://github.com/doug-wade)
- Bo Borgerson [gigabo](https://github.com/gigabo)
- Rob Landers [withinboredom](https://github.com/withinboredom)

Doesn't look like this is available in the API responses we're getting for issues. May need to fetch separately?

Dedupe issues with multiple labels

Currently if an issue has multiple labels that are in the changelog configuration it will get listed in each section. Should only list in one. See entries about <TheFold /> here.

Fails on Windows

I get the following error on Windows -- it is caused by using --pretty='format:' with single quotes in the command. It works if I change it to use escaped double quotes (--pretty=\"format:\").

Error: Command failed: git show -m --name-only --pretty='format:' --first-parent a554e49
fatal: invalid --pretty format: 'format:'

    at checkExecSyncError (child_process.js:483:13)
    at Object.execSync (child_process.js:523:13)
    at execSync (C:\Code\untitled\node_modules\lerna-changelog\lib\execSync.js:15:34)
    at Changelog.getListOfUniquePackages (C:\Code\untitled\node_modules\lerna-changelog\lib\Changelog.js:153:30)
    at C:\Code\untitled\node_modules\lerna-changelog\lib\Changelog.js:103:41
    at Array.reduce (native)
    at C:\Code\untitled\node_modules\lerna-changelog\lib\Changelog.js:101:51
    at Array.forEach (native)
    at C:\Code\untitled\node_modules\lerna-changelog\lib\Changelog.js:98:12
    at Array.forEach (native)

Also, this packages depends on curl executable which is not installed by default in Windows 10. Would be an improvement to eliminate that dependency (or at least call it out).

Consolidate changes by affected packages

The outer list displays packages affected by a given change. This may have multiple entries for the same package or set of packages, which could be consolidated.

For example, here, the outer list could have only two entries instead of four:

---

Enhancement

• generator-react-server
  • #229 Generate meta tags. (@doug-wade)
• generator-react-server
  • #231 Add .reactserverrc to generator. (@doug-wade)
• react-server-test-pages, react-server
  • #221 Add new component: <TheFold />. (@gigabo)
• react-server-test-pages, react-server
  • #224 Expose new convenience function: navigateTo. (@gigabo)

Marking changes as “Unreleased” when tag has been pushed already

I’m trying to generate changelogs and GitHub releases directly from CircleCI when a tag is pushed, but I’m seeing an issue as the changes for the specified range (--tag-from <previous tag> --tag-to <tag that was just pushed>) are being marked as “Unreleased”

Here’s the generation task on CircleCI: https://circleci.com/gh/tusbar/circleci-samples/154

Basically it is running

node_modules/.bin/lerna-changelog --tag-from v1.2.3 --tag-to v1.3.0 > CHANGELOG.md

And the changelog contains

## Unreleased (2017-10-25)

#### :rocket: Enhancement
* [#7](https://github.com/tusbar/circleci-samples/pull/7) Use git-describe to find previous tag. ([@tusbar](https://github.com/tusbar))

#### Committers: 1
- Bertrand Marron ([tusbar](https://github.com/tusbar))

Which is weird as the CircleCI task is triggered just when the tag is pushed to the GitHub repository.

What’s even more weird is that if I run that exact command locally at the same time, I get a valid changelog (with the tag name – v1.3.0 – and not “Unreleased”).

Would you happen to know what’s going on here?
I’m using the same GiHub access token on CircleCI and locally…

Thanks for any help.

The full repo is here: https://github.com/tusbar/circleci-samples

Support separate repo host and issue tracker

The original PR for lerna-changelog assumed issues were tracked on babel's phabricator system. This standalone version currently assumes issues live with the repo on github. Need to make issue URL configurable.

Cached issues and users are never invalidated

Cache invalidation is hard...

... but actually we never invalidate at all which seems bad if you change the issue tags after discovering that something was not properly tagged.

Credit contributors with only un-categorized commits

The contributors list is currently built up from the set of commits that get highlighted in changelog.

Should give credit to all contributors.

Add support for "homu" merge commits

see https://github.com/barosl/homu

we are using that service in https://github.com/ember-cli/ember-cli, which is the primary repo I want to use this generator on.

Progressbar is completed before all requests are done

We are currently calling tick() when we start the request, instead of calling it when the request is finished. This causes the progressbar to be completed before all the requests are done.

Support other folders

Forgot as we moved away for packages/* that any other folder isn't picked up I believe (we added codemods/ and experimental/

I guess to be correct it needs to read from packages key

TypeError: Cannot read property 'map' of undefined

TypeError: Cannot read property 'map' of undefined
    at _loop_1 (/Users/tbieniek/Code/glimmer.js/node_modules/lerna-changelog/lib/changelog.js:271:51)
    at Changelog.fillInCategories (/Users/tbieniek/Code/glimmer.js/node_modules/lerna-changelog/lib/changelog.js:279:13)
    at Changelog.<anonymous> (/Users/tbieniek/Code/glimmer.js/node_modules/lerna-changelog/lib/changelog.js:76:30)
    at step (/Users/tbieniek/Code/glimmer.js/node_modules/lerna-changelog/lib/changelog.js:32:23)
    at Object.next (/Users/tbieniek/Code/glimmer.js/node_modules/lerna-changelog/lib/changelog.js:13:53)
    at fulfilled (/Users/tbieniek/Code/glimmer.js/node_modules/lerna-changelog/lib/changelog.js:4:58)
    at <anonymous>
    at process._tickCallback (internal/process/next_tick.js:169:7)

after running yarn changelog --tag-from v0.4.0 in https://github.com/glimmerjs/glimmer.js

Invalid output when using range tags

This is from running changelog on https://github.com/lerna/lerna

lerna-changelog --tag-from v2.0.0-beta.32 --tag-to v2.0.0-beta.34

https://gist.github.com/hzoo/d9eb42b94824694b79be925f357549eb

Abstract away "providers"

So there are a lot of different systems for getting the information necessary for changelogs.

It would be nice if lerna-changelog could support a variety of different services and systems for generating changelogs by having some abstract form of providers that could be setup in repos.