No good way to handle changelogs for larger teams

[Shardj]

Just having a changelog file which you write to during development is fine for smaller teams. But with larger teams this will cause git conflicts. Also it doesn't work very neatly with any kind of automated deployment as you need to manually change the unreleased tag to the version it's deploying under or use something like sed which would be very unrobust.

I don't know if any libraries exist for this (something I'm looking for) but I'd suggest each new change for the changelog is actually written as a file in a set "changes" directory. This way you get no conflicts as long as you name files after their ticket. And you can automatically write the changes to your main changelog file during packaging/build. Do this by simply adding the date and new tag/release version number to your changelog, then reading files in the changes directory and postpend their contents to the changelog file in whatever format you like, then remove the contents of the changes directory.

If this doesn't exist and the idea interests anyone I'll make a library for it.

[Shardj]

I threw together a quick bash script with the basic functionality of what I'm describing https://github.com/Shardj/teamchangelog

[zanseb]

FWIW: GitLab has a similar approach as you described. More info can be found at https://docs.gitlab.com/ee/development/changelog.html and https://gitlab.com/gitlab-org/gitlab-ce/tree/master/changelogs/unreleased

[Shardj]

Thanks @zanseb that does look like exactly what I wanted. Still looking out for other solutions though if anyone else knows of any although at this point I'm probably going with my custom built solution.

[cbm755]

SymPy uses a bot + PR template [1] which helps contributors write Changelog entries. SymPy has a lot of first-time contributors and for example, that bot points them at appropriate docs.

[1] https://github.com/sympy/sympy/wiki/Writing-Release-Notes

[iocampomx]

Hi @Shardj I thought for a moment your original statement, but monolithic applications came to my mind when you mentioned large teams, I think this is more suitable for microservices and two-pizza teams, which from my experience is the path the industry is following. This is of course not a rule, and I do respect large applications and large teams, but perhaps they need a different mechanism to trace logs.

[Shardj]

Hi @Shardj I thought for a moment your original statement, but monolithic applications came to my mind when you mentioned large teams, I think this is more suitable for microservices and two-pizza teams, which from my experience is the path the industry is following. This is of course not a rule, and I do respect large applications and large teams, but perhaps they need a different mechanism to trace logs.

I absolutely agree, my reasoning is this: keep-a-changelog's suggestion for changelogs pushes itself as the main standard and is suggested everywhere I look on the web. But it completely fails to address the issues I mentioned for large teams. I simply hoped a well maintained library that someone knows of could solve the issues and be mentioned on keep-a-changelog for those who are looking for something more.

[GrahamTheCoder]

https://github.com/olivierlacan/keep-a-changelog/issues/56 helps for some use cases

[mdickinson]

For what it's worth, the approach described in the original issue description is the one that core Python uses. There's a custom tool called blurb which manages creating the news entries and putting them in the right place, along with a GitHub bot that checks that every PR has a news entry (unless there's an explicitly added label saying that a news entry is unnecessary). I don't know to what extent it's possible to use blurb for projects other than core Python.

blurb: https://github.com/python/core-workflow/tree/master/blurb