uphold / github-changelog-generator Goto Github PK

Generate changelog files from the project's GitHub PRs

The objective is to generate a changelog for a specific project in a monorepo.

This tool regenerates a full changelog file based on a project's list of releases and merged PRs. However, that is not enough when dealing with forked projects.

Because forked projects don't preserve the list of releases and merged PRs of their upstream repo, running github-changelog-generator will erase all history and replace it with the changelog specific to the forked repo only.

We don't want that. Generating a new changelog should preserve the existing history. TBD the best approach to achieve that. Some options might be:

• search for multiple git remotes and query their releases/PRs as well (would need to verify the merged PRs are for commits that exist in the main repo)
• query the github API to find an upstream repo and query its releases/PRs (up to the point of the fork)

We can choose on or the other, but not both. Given that this a cli command, I personally don't mind keeping the polyfill and use the node-6 preset as our other projects.

As described in the docs.

We can persist somehow the ETag response header to send it as If-None-Match. Alternatively, we can send an If-Modified-Since.

With this approach we can get 304s for requests that didn't change their response, which means faster responses and fewer increments of the rate limiter.

Right now we're always retrieving the full project history to build a new changelog from scratch.

However, this doesn't scale for large projects. We should only need to retrieve the project history for releases the changelog doesn't have yet. Having only that option or keeping an option to use the old behaviour TBD.

This might require a breaking change, depending on how we decide to go forward.

Linking github-changelog-generator as an executable simplifies its usage.

Simply add the following to package.json:

{
  "bin" : { 
    "github-changelog-generator" : "./bin/github-changelog-generator.js"
  }
}

I think we should use environment variables sparingly and right now, OWNER, REPO and FUTURE_RELEASE look like they could be command line arguments instead.

Combine both files for simplicity?

Running the latest version produces the following warnings:

DEPRECATED (@octokit/rest): `repos.getReleases()` is deprecated, use `repos.listReleases()`
DEPRECATED (@octokit/rest): `pullRequests.getAll()` is deprecated, use `pullRequests.list()`

We need to upgrade to the version >16.

If FUTURE_RELEASE is not set, whatever has been merged but not tagged should be included as Unreleased IMHO.

Suggestion:

*
!dist/

In some projects the generated changelog is showing empty release names. e.g.:

## [](https://github.com/upholdgithub-changelog-generator/releases/tag/1.2.3) (2017-03-07)

That is because the original release was created without a name:

{
  "url": "https://api.github.com/repos/uphold/github-changelog-generator/releases/12345",
  "name": "",
  "tag_name": "1.2.3",
  ...
}

We should default to the value of tag_name, to avoid these empty results.

Until #13 is implemented, the generator should not attempt to include changes that haven't been included in a release.

At the moment, such changes are included in a heading with the same version number as the last release, but with the date of the file generation, which is clearly a bug.

This changelog generator works by finding PR merges and adding them to the latest release. This works fine when we assume all merges are done to master, but is not enough when there are merges to other branches.

Example

Alice is working on a new authentication feature in its own feature branch. It is not yet ready to be merged to master. Bob notices a bug and creates a PR to that feature branch with a fix. Alice merges the PR and continues working on the feature.

Here's the current git tree:

*   432e63f - (HEAD -> feature/new-auth) Merge branch 'bugfix/fix-auth-bug' into feature/new-auth <Alice>
|\
| * 5d9ecbb - (bugfix/fix-auth-bug) Fix auth bug <Bob>
* | 0fad650 - Improve auth test coverage <Alice>
|/
* 3669716 - Implement new auth approach <Alice>
* c04d5c3 - (master) Fix typo <Charlie>

Now, Charlie creates a new release and runs github-changelog-generator to update the changelog with the new release. Here's the current git tree:

*   12f3f12 - (master) Release 1.23 <Charlie>
| *   432e63f - (feature/new-auth) Merge branch 'bugfix/fix-auth-bug' into feature/new-auth <Alice>
| |\
| | * 5d9ecbb - (bugfix/fix-auth-bug) Fix auth bug <Bob>
| * | 0fad650 - Improve auth test coverage <Alice>
| |/
| * 3669716 - Implement new auth approach <Alice>
| |
|/
* c04d5c3 - Fix typo <Charlie>

Here's the generated CHANGELOG.md:

# Changelog

## [1.23](releases/tag/v1.23) (2017-10-17)
- Fix auth bug [#45] (bob)
- Fix typo [#41] (charlie)

The generated changelog is wrong, because Fix auth bug is not yet merged to master and therefore is not actually part of release 1.23. The correct changelog for this release would have been:

# Changelog

## [1.23](releases/tag/v1.23) (2017-10-17)
- Fix typo [#41] (charlie)

It would be interesting to allow filtering not only for merges to master, but also for merges to another designated branch. So, if a team runs releases from branch nightly or dev instead of master, they could still use this generator.

From http://keepachangelog.com:

We can do the following mapping:

• ### Added: pr.head.ref.startsWith('feature/')
• ### Removed: pr.head.ref.contains('remove') && (pr.head.ref.startsWith('enhancement/') || pr.head.ref.startsWith('support/'))
• ### Deprecated: pr.head.ref.contains('deprecate') && (pr.head.ref.startsWith('enhancement/') || pr.head.ref.startsWith('support/'))
• ### Changed: pr.head.ref.startsWith('enhancement/') || pr.head.ref.startsWith('support/')
• ### Fixed : pr.head.ref.startsWith('bugfix/')

WDYT? /cc @fixe @nunofgs

The GitHub release should be the final destination of the changelog, not it's source. We should use tags instead.

Using POST /repos/:owner/:repo/releases we could submit the released changed as a GitHub release.

This allows for a more smooth experience as credentials do not need to be changed.

Instead of pointing to the tag, what about comparing with the previous version?

Example:

• 0.1.0 - 2016-10-06

Currently, the packages fetches all the pull requests after the last release and produces a new item for each PR on the changelog.

However, in my opinion, we should add each commit since the last release, which might or not be associated to a PR. This improves the granularity of the changelog. This has the advantage of also making this module work even if one commited directly to master 😇.

Use sort-package-json.

When the package has no releases, we can't release the first version due to this:

We could use the repository URL available on the package.json when github-changelog-generator is executed to automatically extract the owner and repository information.

Example:

Running github-changelog-generator on a project with the following package.json:

{
  "name": "Foo Bar",
  "version": "1.0.0",
  "repository": "[email protected]/uphold/foobar"
}

Should be able to set the default value of --owner to uphold and --repo to foobar.