Repository navigation
Have a proper CHANGELOG(.md) #11
Description
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.
Activity
daenney commentedon Jan 14, 2020
@at-wat @Sean-Der Thoughts? Ideas?
Sean-Der commentedon Jan 14, 2020
I am behind this 110%
I have had multiple people email me and say
Hey this is fixedorHey this regressedand 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 :)
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 commentedon Jan 14, 2020
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:
and on a new version release, a release script replaces
ForthcomingbyVERSION (DATE)automatically.daenney commentedon Jan 14, 2020
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.
daonb commentedon Jan 16, 2021
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 commentedon Feb 22, 2023
I am adding a link to this comment by Sean about conventional commits:
#143 (comment)
Maybe it could be a way to generate a Changelog automatically
Sean-Der commentedon Sep 2, 2025
When we tag commits a changelog gets generated now. See this for example.
This could always be improved, but for now it seems to be working well for people!