new: dev: add gitchangelog to generate change log

[ChrisZhangProdigy]

What kind of change does this PR introduce?

Add gitchangelog as a tool for generating change log. It comes with a default config file .gitchangelog.rc. I also include the CHANGELOG.md which is generated by the tool. We probably need to do some manual adjustment on it. And in the future, we can use gen-changelog-delta make command to generate new change log, which will be added to the base version. In order to make the tool work properly, we need to follow some convention in commit message. Which will help the tool categorize different changes, and determine if those changes should be included in the CHANGELOG.md.

This PR is the first draft on how we can use the tool. In the future we can make this process a sub routine of build/publish.

What is the current behavior?

What is the new behavior?

Does this PR introduce a breaking change?

N/A

Other information

[DaleSeo]

@ChrisZhangProdigy Could you create a branch in this repo instead of in a forked branch? That will allow your changes to get linted and tested properly by Github Actions because it's currently configured to be triggered on every push to this repo.

[DaleSeo]

@ChrisZhangProdigy Sorry, I added the above comment before looking at your changes. Maybe you don't need to do that for this PR that doesn't contain any actual code changes.

[DaleSeo]

LGTM but it looks like this tool would shine more if it was integrated into our Upload Python Package workflow on Github Actions because we would want to automatically leave a changelog on every release. I'll work on that once this gets merged.

[steve148]

This PR SHOULD be triggering the CI checks, no matter if the Pull Request is coming from a forked repository or from a branch on this project. In the future I would like to not allow anyone the ability to create branches on the base repository here, as we can't have stale branches if there are no branches (following along the lines of the serverless model, this repo should try and be branchless™).

I think I have a fix up that solves this at #20. I'm not worried about the checks not running on this PR as it was my fault in the first place.

[ChrisZhangProdigy]

@steve148 I think you may want to review the CHANGELOG.md and make some adjustment since you have more context on the project.

[steve148]

@ChrisZhangProdigy sorry for being slow with the review here.

Can you provide an example of how to run the gen-changelog-delta command?

[steve148]

Ok so as I'm reading through this, I'm reconsidering my original thought of automating the process of creating a Changelog / release notes.

Here's what I see as the pros and cons for an automated changelog / release notes generator.

Pros

• Reduces a bit of the work on the maintainers of the project to when cutting a release.
  • Counter point. Doesn't fully automate it / may not be useful if fully automated. Second part true if commit messages exactly clear on their change / output.
• Forces contributors to commit with messages that match the format expected by the project. More consistent commit messages means more consistent history and easier to understand what each commit does.
  • Counter point. Commit message style may change over time, so the idea of consistent git commit messages may not be as useful.

Cons

• Still requires some manual step to update the changelog.
  • Counter point. Less manual work is better though.
• Creates an entry in the changelog for each commit instead of each pull request. Pull Request which encapsulates a feature can have multiple commits in it.
  • Counter point. Ideally pull requests / changes are only a single commit, assuming we are doing proper git commits.
• Changelog doesn't take advantage of github to link to authors or pull requests that commit(s) come from.
  • Counter point. If we move off of github then we wouldn't have this anyway. Not that we are moving off github anytime soon, but still a risk.

Without this change, the process of releasing looks roughly as follows:

1. Update the version of the package in setup.py in a new commit.
2. Push commit to master.
3. Create release in github, using the commit that bumped the package version for the git tag. Manually write the release notes on the github release. Creating the release triggers a github action which builds and pushes a new version to PyPi.

With this change the process stays roughly the same, minus the manual write up.

I'm sorry for flip-flopping on my opinion on the value of this improvement. I think there's still value to this, I'm just not sure whether this work was early optimization for the problem of managing releases when this isn't really an issue right now. I'd like to talk more about it if that's ok with @ChrisZhangProdigy and @DaleSeo.

[ChrisZhangProdigy]

@steve148 I agree on the pros and cons you pointed out. When I worked on this task, I found it is not easy to auto generate a good change log. Therefore, I am thinking we can make this tool optional. For example, using it to create a draft before we manually compose the change log. If we are satisfied with it, we can add it into the pipeline (However, manual adjustment may be still required from time to time). Here are the answers to some of your questions:

1. To generate delta: make first-tag=v0.1.0 last-tag=v0.2.0 gen-changelog-delta
2. Do not want to generate an entry for every commit:
   The format of the commit message is: ACTION: [AUDIENCE:] COMMIT_MSG [!TAG ...]
   A commit message with AUDIENCE pkg, dev or TAG !minor, !cosmetic, !refactor, !wip will be ignored. (We can change figure as well).
   As long as we follow the commit message convention, it should be manageable.

[steve148]

Ok so going through the Changelog file, here is what I roughly expect / would like to see as the output for that file. Specifically note that it's a single line item per pull request not commit.

I'm happy with the changes here and am happy to approve them, but we'll need to do a lot more work / have a lot more usage of this project to make sure this changelog generator is streamlined. As a next step, if we expect people to use a specific commit message style then we should add a linter for that. For example / inspiration https://github.com/conventional-changelog/commitlint.

# Changelog

## 0.2.0 (2020-01-24)

### Other

* feat: create pypi publish github action chore. #8 [Lennox Stevenson]
* Allow overriding headers when making requests. #10 [Dale Seo]
* feat: create config for linter checks. #11 [Lennox Stevenson]

## 0.1.1 (2020-01-22)

### Other

* Fix/setup fields #1 [Lennox Stevenson]
* Link to new public repository on contributing guidelines. #2 [Dale Seo]
* Add the Black label :medal_military: to show our style :nail_care:. #3 [Dale Seo]

## 0.1.0 (2020-01-22)

### New

* Feat: initial commit. [Lennox Stevenson]