Add support for generating Changelog.md file

It’s great the github releases are automatically generated, but as a user of changelogs I find it more useful to just look at a single Changelog.md file instead of having to page through (sometimes) numerous pages of github releases to understand all the changes that happened between the version I was at and the latest.

It would be great if release were to also automatically generate and update a Changelog.md file and drop it into the root of the repository.

Edit: I would be happy to implement this if it would be used for the generation of releases in next.js

This is following up a discussion had with @timneutkens in the next.js channel.

[hellais]

@Qix- thanks for your detailed response. You bring up some very valid points that I hadn’t considered

[Qix-]

Well by that logic then this tool should not exist at all.

This tool isn’t for generating changelogs though. It’s to automate the process of releasing an npm package to the central repository and including the relevant details on the Github release page as a convenience to users.

But realistically, anyone inside of a Git repository looking at a changelog could just run the relevant git command if that’s what they’re after.

Moreover, the git diff command, doesn’t extract git commits, which means stuff to humans, but rather it generates a diff of the files in the tree.

Correct, sorry. I meant git log - the syntax of the commit range remains the same.

If you have ever had the unfortunate experience of using it to learn what are the changes between two releases of any non-trivial bit of software you will know it’s not exactly a simple tasks.

I use both commands frequently to do my job as I don’t like to rely on humans to tell me what parts of code have changed. If I care to know exactly what happened between two points in time, I will trust a git diff - even a lengthy one - over a changelog any day of the week, personally.

So you’re right, I’ve not had an unfortunate experience. But to each their own, I understand Git has a little bit of a learning curve.

It’s generally much easier, assuming the developer follows good practices when writing their commit messages, to look at the commit message history.

Right - but the problem with changelog files themselves is that they are an artifact of information derived from the repository contents. Artifacts are generally considered bad practice to include in a repository for two reasons:

1. In many cases, they produce 1:1 or even n:1 (n > 1) changes related to other parallel changes in the commit(s) - meaning that for every one change you make in place A, and for where B depends on A, B may have at least as many changes a A just because B is an artifact. This clutters commit logs and makes PRs an increasing headache to triage and approve, especially when you have 10’s to 100’s of repositories to manage.
2. Artifacts desynchronize without human intervention or maintenance. This means that if somebody changes A, they must also re-produce/-compile/-transpile/-export/-etc B in order to produce a set of changes that are ‘complete’ as a single commit. Otherwise, B won’t reflect the up to date by-product of A. Further, since build processes (such as a compilation step) aren’t always determinant or reproducible, this can potentially cause problems or even security risks/vulnerabilities in repositories.

While changelogs aren’t (normally) a risk to include, philosophically they do not belong in the repository as the git log contents are to be considered the source of truth.