Np: optional CHANGELOG generation with conventional-changelog-angular format

[bcoe]

Problem Statement

I've become a convert to using a conventional commit format when squashing commits on my various OSS projects:

• with nyc and yargs I was finding it valuable to (and people requested that I) maintain a CHANGELOG:
  
  
  
  • it's useful for forensic analysis when bugs are released.
  
  
  • it helps communicate outwards to the community about the work you're doing.
  
  
• unfortunately, I found that CHANGELOG maintenance was a nuisance -- it would add several minutes (at best) to the release cycle while I groomed the file, and collected information for it.

I wanted a CHANGELOG, but I didn't want to put work into maintaining it!

The Solution

• I _don't_ require that contributors to the project use a special commit format.
• I take advantage of GitHub's squash button, and craft a formatted message while I land pull requests (this adds almost no cycles to my workflow).
• I currently use the standard-version tool to cut a release from the git history that has been landed.

Here's what you end up with:

https://github.com/yargs/yargs/blob/master/CHANGELOG.md

Proposal

• it would be great if we could add CHANGELOG support to np.
• rather than requiring this functionality (I understand not everyone will want to craft commit messages) we could add a new option flag --changelog?
  

  Why?

Various folks in the conventional-changelog org have expressed an interest in working together more closely with you (CC: @nexdrew, @Tapppi).

Personally, I'd like to find ways to continue standardizing on commit message format/release management. I'm excited by projects like @boennemann's semantic-release, I've also been talking to the folks at coveralls.io about the idea of creating activity feeds for your coverage history based on parsing this format (CC: @nickmerwin, @anjin).

tldr; there's lots of cool stuff happening around CI/CD right now, and we should try to work together as much as possible.

[nexdrew]

IMO the most compelling reason to integrate something likestandard-version with np is the auto semver bump - I personally find it much easier to think of how a change should affect the next version when reviewing/merging the change rather than when I want to cut a new release; the changelog generation is just the icing on the cake.

[nexdrew]

As @Tapppi mentioned here https://github.com/conventional-changelog/standard-version/issues/72#issuecomment-231596687, this could possibly be implemented as a custom "version" command as well e.g. by allowing standard-version to be used in place of npm version ${arg}.

[dignifiedquire]

I'm actually in need of exactly this and currently trying to figure out if there is a nice way where I don't have to forknp, so I would be very interested in working on this and figuring out a nice solution so I don't have to duplicate all the work that already is in np.

[zeke]

I would love to help make this happen. I'm a big fan of np and would like it even more if it had changelog support.

@sindresorhus are you open to this?

@bcoe it's been a while. Are you still interested in working on this, or have you moved on to another solution?

[bcoe]

@zeke I'd still be interested in helping with this; from the point of view of the conventional-changelog ecosystem which I love contributing to -- I think simple structured commits are a good idea, and fit well with semver.

[sindresorhus]

Honestly, the main reason I never liked the Angular style commit convention is that the commit messages doesn't look very good. I also don't think I would ever use scopes. It would be a much easier sell if commit messages were just Fix: That bug, Feature: Add this. Commit messages shouldn't look like metadata. I was also initially turned off by having to get contributors to follow the guidelines, which we know no ones does, but that's an almost solved problem now with the Squash button.

I also don't like how it generates a CHANGELOG.md in the repo. I strongly feel the changelog should only be in GitHub Releases.

I take advantage of GitHub's squash button, and craft a formatted message while I land pull requests (this adds almost no cycles to my workflow).

I already edit every single title as very few contributors are able to create good titles. But what if squashing is not suitable? Sometimes a PR is split into maybe 3 individual pieces (commits) that makes sense own their own, but wouldn't make sense as 3 PRs. I want to rebase, but then I would have to do the chore of getting to contributor to follow the guidelines...

rather than requiring this functionality (I understand not everyone will want to craft commit messages) we could add a new option flag --changelog?

It's not just the changelog though, it also picks the correct version bump for you, right? So if a commit has "BREAKING CHANGE" it makes it a major. I think --conventional might make more sense.

[sindresorhus]

// @SamVerschueren @gillchristian

[stevemao]

I also don't think I would ever use scopes

Scopes are optional. fix: That bug should just work. we are adding support for configuring stanza in your package.json so that you could, for example, add more verbs.

I also don't like how it generates a CHANGELOG.md in the repo. I strongly feel the changelog should only be in GitHub Releases.

We do have a github releaser. But it's not host agnostic. CHANGELOG should just be as important as README, CONTRIBUTING, LICENSE etc. You wouldn't want to tight README to only github.

It's not just the changelog though, it also picks the correct version bump for you, right?

This is definitely possible. I don't think it's supported in standard-version now but we can work it out.

Sometimes a PR is split into maybe 3 individual pieces (commits) that makes sense own their own, but wouldn't make sense as 3 PRs.

This shouldn't be related to this issue. We'd have the problem whether we generate CHANGELOG or not

I think you like CHANGELOG and we can work the details out to address your concerns :)

[sindresorhus]

But it's not host agnostic.

I don't really care about being host agnostic. Like most people, I only use GitHub.

CHANGELOG should just be as important as README, CONTRIBUTING, LICENSE etc. You wouldn't want to tight README to only github.

Readme, contributing, license, etc, describe the current. The changelog describes the past. I don't want that kind of noise in my repo. GitHub Releases is IMHO a better solution.

[Tapppi]

Readme, contributing, license, etc, describe the current. The changelog describes the past. I don't want that kind of noise in my repo. GitHub Releases is IMHO a better solution.

I know as a user of modules I always look for release notes with the source code, since it is agnostic to the release platform. IMHO the changelog tells users how to switch to using the current version, and as such is as important as README etc.

The alternative is using the github releaser as said previously, and our recommended workflow is just to run them one after the other, which works splendidly. The conventional-* packages are pretty flexible, since they have been broken down to modules, but it can be hard to find the right workflow to get what you want.. We can definitely help with that.

It's not just the changelog though, it also picks the correct version bump for you, right?

This is definitely possible. I don't think it's supported in standard-version now but we can work it out.

Standard version DOES pick and execute the correct version bump as well. That is the second biggest benefit of a conventional commit format IMHO, as I have absolutely no desire to sort out what version bump I should be doing for tens of packages after doing commits to them and knowing what those changes are when I'm doing them.

I want to rebase, but then I would have to do the chore of getting to contributor to follow the guidelines...

Yes, this is the biggest drawback. If the PR has multiple commits that make sense to merge as separate commits, it isn't hard to rewrite them, but it is hard to get a first time contributor to do it. I'm not sure what would be the easiest way of getting that workflow worked out so that a maintainer can rename them.

[zeke]

The changelog describes the past.

It also describes the present. The past behavior and the present behavior are key considerations when updating a dependency.

Like most people, I only use GitHub.

Yeah of course we all use GitHub. Heck I even work for GitHub! But that doesn't mean GitHub should be the canonical home of the change log. That should be the repository. The repo should include the changelog, and the body of each GitHub release should be derived from the change log.

[gillchristian]

there's lots of cool stuff happening around CI/CD right now, and we should try to work together as much as possible.

I like the idea of working together and automating stuff. I think that's great.

Maybe having it opt in would be a good idea. Since different people might have their own reasons for including or not a CHANGELOG.md, and specially because not everybody would want to force a convention on the commit messages.

[simonhaenisch]

I started working on a package more, and want the publishing process of np but also the automatic generation of a changelog, so I'm currently trying to work around it like this:

{
  "scripts": {
    "changelog": "conventional-changelog -p angular -i changelog.md -s",
    "release": "np && npm run changelog && git commit changelog.md -m 'chore: update changelog'"
  }
}

but that results in an extra commit (and I still need to manually pick the version, which I'm actually fine with).

Update: I created a pretty PR for this. Let me know what you guys think.

[webpro]

The owner of release-it here. This will probably come across as a shameless plug or off-topic. Anyway, this might serve as an example how (not) to do it. I'm also genuinely interested in feedback or opinions regarding the way release-it handles this (or the tool in general). It supports (custom) or conventional changelog, including the recommended bump.

[zeke]

Thanks for sharing, @webpro. I hadn't seen release-it.

[cereallarceny]

The auto-changelog package suggests you do the following:

"scripts": {
  "version": "auto-changelog -p && git add CHANGELOG.md"
}

That's what I do in all my packages with release-it @webpro, but I haven't yet tested this in np. I figure it should work since it just hooks on to the version script. Whenever npm version is run, it should run that command. Would this work in np?

[itaisteinherz]

Note that np currently does this (sort of) when creating a GitHub release draft.

I don't think that np should have built-in changelog generation, as that would be beyond the scope of this project and require a lot of time and effort to maintain. However, this can be done by using npm lifecycle hooks (see the comments above).

This is also related to #386, which I'd love to see some input on.

[itaisteinherz]

@sindresorhus Can this be closed? It seems to me like we've already implemented most of what's being suggested here, in one way or another.