feat(changelog): autogenerate CHANGELOG.md from conventional commits

[liangyuanruo]

Problem

A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project. Not having a changelog makes it difficult for developers and open source users to understand the major changes during each release.

Additionally, the use of conventional commit messages are hidden away in the git logs, with some effort required for manual release tagging.

Solution

Automatically generating and updating a changelog

Use auto-changelog to automatically add git log messages to the CHANGELOG.md during version bump.

Release workflow

1. Develop as usual using conventional messages for each commit message

2. During release, use npm version with -m flag to add a custom conventional commit message to tag the git version and auto-populate the changelog.

For example:

Yuanruos-MacBook-Pro:formsg gt-liangy$ npm version patch -m "chore: version bump to v4.33.1"
v4.33.1

> FormSG@4.33.1 version /Users/gt-liangy/Developer/formsg
> auto-changelog -p && git add CHANGELOG.md

auto-changelog: 17 kB written to CHANGELOG.md

In CHANGELOG.md:

+#### [v4.33.1](https://github.com/opengovsg/formsg/compare/v4.34.0...v4.33.1)
+
+> 9 September 2020
+
+- chore(deps-dev): bump eslint-plugin-jest from 23.20.0 to 24.0.0 [`#299`](https://github.com/opengovsg/formsg/pull/299)
+- fix(deps): bump ejs from 2.7.4 to 3.1.5 [`#282`](https://github.com/opengovsg/formsg/pull/282)
+- chore: document env vars needed for EFS [`#303`](https://github.com/opengovsg/formsg/pull/303)
+- Greater clarity for available features, project roadmap and deployment instructions; disable E2E tests [`#301`](https://github.com/opengovsg/formsg/pull/301)
+- doc(changelog): generate changelog with 'npx auto-changelog' command [`2be96c4`](https://github.com/opengovsg/formsg/commit/2be96c415c245f4d8c9f68c53bb6456d16f2e87b)
+- feat(changelog): install auto-changelog and include it in npm version command [`0bdfd60`](https://github.com/opengovsg/formsg/commit/0bdfd6096951845b8007d2ae4e2aa9ad6181fe28)

Features:

• Automatic changelog generation from conventional git commit messages

Improvements:

• Remove manual effort required to compile changes in the GitHub pull request during release (only if commit messages are clear)

Deploy Notes

New dev dependencies:

• auto-changelog : For auto-generation and update of CHANGELOG.md

[arshadali172]

@liangyuanruo @mantariksh opinion piece on why projects shouldn't auto-generate change logs from commits: https://dev.to/jonasbn/why-and-how-should-you-write-a-good-change-log-4kp0

[arshadali172]

I'm thinking we can look at this package instead? It seems more widely used to compared to auto-changelog.

Read more at: https://itnext.io/automate-your-releases-versioning-and-release-notes-with-semantic-release-d5575b73d986

[arshadali172]

Check out the library I suggested and weigh the pros/cons?

[liangyuanruo]

Check out the library I suggested and weigh the pros/cons?

Noted on that, I was discussing with @LoneRifle and we think semantic-release may be too powerful to safely introduce. It removes control of semver completely from the developer since the version bump is run after a release is pushed out on TravisCI.

I am also aware of the downsides of auto-generation of changelogs from git commits. My intent is to

1. Reduce/automate workload on the weekly release manager to write a nice changelog when tagging a release, especially since we haven't been doing this at all for the last few releases. With proposed approach we can cut a release merely by bumping the release version.

2. Retain flexibility to reword updates to the changelog if necessary via git rebase

The main thing to watch out for is to carefully name the title of each PR as it will make up the content of the changelog.