Comprehensive changelogs

[m-allanson]

View formatted

After getting this all down on (virtual) paper, I feel like option 2 with the add-on gatsbot comments seems like the most practical approach for right now.

I'd love to see option 5 implemented at some point, but I don't think the time to implement is worth the benefits yet.

Feedback welcome!

(👀 for a companion RFC dealing with changelog formatting, coming soon see here)

[pieh]

This is not quite accurate - right now changelog entries are only added when using feat, fix or perf prefixes. That's because we use default changelog generation preset used by lerna (or deps of lerna - didn't research that much), which is conventional-changelog-angular (note about type in preset docs: https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular#type and relavant part in code of preset: https://github.com/conventional-changelog/conventional-changelog/blob/d3c2432f695d1b7f33c384be0bcb6495274ddca8/packages/conventional-changelog-angular/writer-opts.js#L44-L45 )

We definitely can fork this preset and adjust to our needs. I did some local tests with adjusting preset to use all the prefixes (result can be seen in https://github.com/pieh/lerna-playground/blob/master/packages/package-b/CHANGELOG.md - with my changes there are actually entries for other prefixes like docs or refactor)

[m-allanson]

Oops, thanks. Let me update this to make it less wrong 😅

[wardpeet]

if we don't want to fork and just want to enable a list of types & scopes we can use
https://github.com/leonardoanalista/cz-customizable

We can let cz-config scan our folder structure to always give an up to date scope list of all packages we have.

[pieh]

I don't think forking is big problem here. We would need to do it (or change preset at very least) if we want to enable changelog entries for different commit types and extra notes, because right now it will pull text for extra config only if BREAKING CHANGE is used (which we obviously don't want to use for something that is not breaking change.

Scope doesn't actually tells which changelog should be generated - it only adds this part to changelog

Lerna is smart enough to check what packages were changed in commit and adds changelog entry for each of those packages.

[wardpeet]

oh yeah we have have a changelog in each package.. My bad I was thinking of a global one.

so actually the scope doesn't has to be the package name as lerna figures it out. So we just need consistent commits so we can tell lerna what types we support?

[pieh]

If we enforce PR title, we can actually do a lot of stuff in changelog preset - i.e. if commit message itself is not following conventional commit, we can do GitHub API request to read additional metadata for commit, find PR and use PR title for changelog entry.

This would work for titles, but if we want to add additional information to changelog entries we would need to also figure out way to add additional notes in PR description and parse this information in changelog preset. This could actually worked nicely if we edit PR template to have CHANGELOG entry section and validate that with Peril

[wardpeet]

we might want to update commitlintbot or whatever bot that already exists to do this behaviour. Another option is that we could add the feature to refined github plugin.

[wardpeet]

if we don't want to fork and just want to enable a list of types & scopes we can use
https://github.com/leonardoanalista/cz-customizable

We can let cz-config scan our folder structure to always give an up to date scope list of all packages we have.

[wardpeet]

we might want to update commitlintbot or whatever bot that already exists to do this behaviour. Another option is that we could add the feature to refined github plugin.

[wardpeet]

I guess there is the https://developer.github.com/v3/activity/events/types/#pullrequestevent event that might trigger this

[pieh]

I just edited PR title - and this is webhook that gets triggered:
- so Peril can definitely listen to it

[wardpeet]

I'm voting for 4. This will be a good starting point, we should still iterate on it to get some more info inside the pr-template for context.

One thing that's probably going to help us a lot is to update refined GitHub extension to automatically copy & paste the title into the commit message so we (mostly I) don't make mistakes)

we probably want to version with https://github.com/lerna/lerna/tree/master/commands/version#--changelog-preset as @pieh already mentioned we'll need our own preset.

I feel like option 2 with the add-on gatsbot comments seems like the most practical approach for right now.

We want this as well to just make sure we don't lose any commits inside the changelog but I feel like it's up to the publisher to make sure all uncategorized ones are manually edited inside the changelog.