Changelog management

[isaacplmann]

Note: for support questions, please use one of these channels: Chat: AngularClass.slack or Twitter: @AngularClass

• I'm submitting a ... [ ] bug report [ ] feature request [x] question about the decisions made in the repository

If I wanted to add semantic-release to handle changelog generation, would that go in the root package.json or the individual library package.json?

[shlomiassaf]

changelog is managed in the repository so I guess root.

Make sure to install as dev dependency.

I would love to hear about this idea, maybe a PR. :)

[isaacplmann]

I'm trying to think through how this would work myself.

I want to be able to have a CHANGELOG.md for each library - so one each for @corp/core, @corp/common, and @corp/rare.

semantic-release adds hooks that automatically update a CHANGELOG.md and publish to npm any time the master branch is pushed to github. So I think I'd need to have separate git repos for each library - I'm not sure if that's even possible.

[isaacplmann]

This issue makes it seem like semantic-release might not be the best solution for managing multiple npm packages in the same git repo. It looks like lerna and lerna-semantic-release can handle that situation, but lerna might be adding more dependencies than you want.

[shlomiassaf]

Maybe its worth looking at the angular repo, see how they tackle this

[jskrzypek]

@isaacplmann if your commits are scoped with the name of the library that was changed in the commit (similar to how angular does it) then it would certainly be possible to generate a changelog individually for each package.

[isaacplmann]

@jskrzypek Does semantic-release do that automatically, or would I have to write my own script to parse the commit messages?

[shlomiassaf]

@jskrzypek @isaacplmann Scoping by convention works well but requires discipline.

On angular it works, on the wild west it will work for some and cause havoc for others...

In the repo i've implemented version bump helpers (in gulp, still not exposed as npm script).

gulp release:detect

Will check the src directory of every library, if the commit has changed since last time it will notify a bump is required.

example

gulp release:commit
  
[22:10:58] Starting 'release:commit'...

The following packages need a bump: 
{
  "angular2-modal": {
    "commit": "a5da320f0f558ba0e631785a6987e698b00f677c",
    "version": "3.0.0"
  }
}

gulp release:commit

Will log all the commit hash's for every library into a file. This file is used by release:detect to detect bumps.

filename is version_cache.json in repository root.

---

Now assuming we use this logic, or a variation of it, we can tell conventional-changelog the boundaries. I have no clue if it is supported by conventional-changelog but its a idea im throwing.

[shlomiassaf]

This is tricky, not sure there is a simple solution here...

While @angular does use scopes in their commit messages they generate a single CHANGELOG for all scopes.

https://github.com/angular/angular/blob/master/tools/gulp-tasks/changelog.js

This actually makes sense, some changes might be cross-library... yes each commit can be per library/scope but it becomes difficult to express the right message that way.
Sometimes a commit involves 2 libraries/scopes and it is logically correct to make the same commit on both...

Some commits does not have a scope but does have a type, they have that in angular....

So in those cases the solution is a single top-level CHANGELOG, otherwise there will be issues, complex ones.

Now, tricky I said... this all goes well as long as all libraries are aligned to the same version.
In the angular project a version bump is global, to all packages, even untouched ones.
Again, in their scenario this makes a-lot of sense.

BUT, if you just the repo as a collection for unrelated libraries under your (npm)scope, that's a totally different thing.
For that scenario the only option is a custom setup using similar logic to larna...

Not sure its worth the effort.