Include standards for large changelogs?

[KeithHenry]

Should these standards also include best practices for long running projects?

For instance, I have large project that's used this for a couple of years, but a weekly release schedule (plus a lot of patches) means CHANGELOG.md ends up many thousands of lines long.

I want to keep the old release documentation, but only maintain the current releases.

My current solution is a CHANGELOG directory, containing 0.md, 1.0.md, 1.1.md etc, with each containing the minor releases (so 1.1.md holds 1.1.0 to 1.1.*, and then 1.2.0 moves to a new file).

This ends up very idiosyncratic, and if there is a standard/best practice way to do this I want to follow it.

Should the standards FAQ sections here include common patterns for very large changelogs?

[b-dean]

I like what Terraform does with their changelog.

Basically since the CHANGELOG.md is committed, just link to the CHANGELOG.md at an older revision. Then you don't actually have to keep them around in your working directory.

[KeithHenry]

Oh @b-dean I love that idea, but you need to plan for it from the start by keeping the version number in your notes current.

Go back to any of our release tags and the changelog would list the current release as "unreleased".

I'm not sure how to switch to it given a existing project.

In addition you can't really go back an amend old notes (without branching), but we can get old release notes wrong and have to go back and fix them.

[martins-1992]

Maybe add a link to the folder containing older changelogs inside the top level changelog.
Thereby the folder could be located at other locations as well.
Also, somebody thereby will find the other changelogs without knowing of this format as well.

[b-dean]

@KeithHenry, I know what you're talking about and I've seen it a lot - where the CHANGELOG.md in a version tag has all those changes still under the Unreleased heading. Do you know why things often end up that way? It seems to me that the "preparing for a release" work, which includes tagging the repo with the version number, should also include putting that version number and date in the changelog. After all, if you know what the version is to tag it, certainly you could have the changelog up-to-date right?

But it seems pretty common to not do that. I see it in repos at my job all the time as well as open source stuff on github. Probably just oversight.

That being said, if you have a tagged revision and the URL has the version number in there, it's not too difficult to interpret what the version is. In the link earlier to the Terraform changelog, I think they're actually linking to a branch for older changelogs. That way they could go update it if they wanted.

Seems to me like the best practice would be to have the changelog current with the version being tagged (including the link to the comparison w/ the previous version) before the tag is applied.