Have a proper CHANGELOG(.md)

[daenney]

Summary

I think we should start maintaining proper CHANGELOGs across the projects. I would propose to adopt the https://keepachangelog.com/en/1.0.0/ format for this.

Motivation

I feel extremely awkward having to add myself to the README whenever I contribute even the most minuscule changes to a pion repo. On the one hand I appreciate the shout-out, on the other hand, it's awkward. It's also a bit out of the ordinary compared to most other projects as far as additional things you need to do when contributing.

Instead I would propose to move attribution into a CHANGELOG(.md). This is a far more common place to keep information around who has contributed to what, and would also let us attribute actual changes over time more easily to individuals than a single static entry in the README. Expecting PRs to also provide a changelog entry, when necessary, is also fairly commonplace.

Though there are many ways to maintain a changelog, I like the idea of having something that is at least standard across our repos, and as such I'd say we should follow the https://keepachangelog.com/en/1.0.0/ format. It might not be an industry wide standard, but at least it's a document we can point everyone at (which limits the amount of bike shedding around the format) and in general results in fairly nice changelog entries. We use the format in flask-dance if you want to get a sense of what it looks like.

Having a somewhat standardised format also makes it easier to create tooling around that format, which has already been done in other languages, like https://github.com/contentful-labs/keepachangelog.

Alternatives

We've had discussions before about switching the commit format to Conventional Commits. If we do that, we'd probably be better off generating the changelog automatically using the Conventional Changelog set of tooling instead. We could also use something like git-chglog to generate a Convetional Changelog.

The reason I'm proposing Keep A Changelog over Conventional Changelog is that the latter is highly dependent on using the Conventional Commits format everywhere, requiring us to put that in place before we get to this.

[daenney]

@at-wat @Sean-Der Thoughts? Ideas?

[Sean-Der]

I am behind this 110%

I have had multiple people email me and say Hey this is fixed or Hey this regressed and having a nice CHANGELOG would have made everything so much easier. After fixing the config drift issues @at-wat is doing this is my second biggest organization frustration with Pion.

---

I am in full support of doing CHANGELOG + standardized commit messages (instead of the arbitrary rules we have right now). @hugoArregui started this here but I just haven't had a chance to get it going everywhere. I am happy with whatever we do! It doesn't matter what direction we move to me, as long as we have something better :)

It's also a bit out of the ordinary compared to most other projects as far as additional things you need to do when contributing.

I am torn. I really want to incentive/reward people that get involved. Especially people that are afraid to get involved in Open Source for the first time. I would be curious if this actually mattered to anyone. If it actually hasn't had an impact I would say delete it. Maybe this is worth a poll we can share via Twitter/Slack?

[at-wat]

Sounds nice to have a CHANGELOG.

Just FYI, I usually work with a middleware Robot Operation System. It has a script to gather commit messages like:

### Forthcoming
- Commit message (#Issue_number)
- Commit message (#Issue_number)

### PREVIOUS_VERSION (DATE)
- Commit message (#Issue_number)
- Commit message (#Issue_number)

and on a new version release, a release script replaces Forthcoming by VERSION (DATE) automatically.

[daenney]

It's also a bit out of the ordinary compared to most other projects as far as additional things you need to do when contributing.

I am torn. I really want to incentive/reward people that get involved. Especially people that are afraid to get involved in Open Source for the first time. I would be curious if this actually mattered to anyone. If it actually hasn't had an impact I would say delete it. Maybe this is worth a poll we can share via Twitter/Slack?

So, I'm not sure if it has an actual impact. But I got caught by it when submitting this PR, since it's my first one to this repo, and my brain went "huh, that's weird". I honestly don't know if it matters at all, but it was a bit weird to see my PR fail on it.

[vidavidorra]

Based on my discussion in Slack (starting from this message), I'd like to work on this in the near future. In short: I'd plan to be using Conventional Commits and probably Standard Version to automatically generate a changelog (and perhaps automated releases if we want to).

[daonb]

Seems like it's still undecided: automated change log based on commit messages or doing it by hand. IMO, change logs should be maintained by us humans as they are targeted at the user unlike commit messages which are targeted at developers. Commit messages are more technical in nature and more detailed and while some commit messages can be copied directly to the change log, most are too detailed|cryptic for the non-developer.

FYI, There is a github action, mindsers/changelog-reader-action, that reads the changelog (provided we adhere to keepachangelog format) and extracts the version information. Here's how I use it.

[stv0g]

I am adding a link to this comment by Sean about conventional commits:

https://github.com/pion/.goassets/issues/143#issuecomment-1425165639

Maybe it could be a way to generate a Changelog automatically