You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Note: This discussion is a bit more specific than #529.
I am big proponent of keeping a changelog and I think at my employer we were early adopters of this standard.
Thus we have kept changelogs now for quite some time (actually years) of our applications under active development.
That is why our changelogs have gotten rather long and I was thinking about how to archive them "properly".
One issue with long changelogs in the Markdown format is that rendering them gets longer and longer, which could even lead to tool timeouts or unresponsiveness of the displaying tool.
Mentioning the major or major and minor version in the changelog, current or archived, can work well for projects adhering to SemVer.
For example, PHPUnit uses the changelog file name format ChangeLog-x.y.md but does not keep an archive, except for the ones in branches of previous release channels.
But in our case, we adopted a non-SemVer-style versioning. We do not have major or minors but are date oriented (YYYY-MM-DD ).
Possible solutions:
Just don't care, delete old changelog entries since one could go back in commit history.
Tag the revision, remove old changelog entries and link to that tag
Move old changelog entries to a single CHANGELOG_ARCHIVED.md file. Since it is an archive, it's not used that often, thus it doesnn't matter if it takes longer to load.
Move old changelog entries to changelog files split by year, e.g. CHANGELOG_2022.md, in a (possibly) dedicated changelogs folder. Whether splitting by full years is sensible depends on the project itself.
Optionally, one could link from the main CHANGELOG.md to the archived ones.
Other considerations:
Always keeping a single changelog file, such as CHANGELOG.md, even with archiving entries, just increases the commit history of the file. Which still can lead to longer loading time, e.g. when doing git blame or the like.
Renaming and/or moving the current changelog file from /CHANGELOG.md to something/somewhere else keeps the git history of that file and its changelog entries.
One can then create a new, current /CHANGELOG.md and stat anew.
Anyway, I would propose to include some recommendations for hanlding/archiving large, long-running changelogs of projects (SemVer or not) in the FAQs of the standard.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
-
Note: This discussion is a bit more specific than #529.
I am big proponent of keeping a changelog and I think at my employer we were early adopters of this standard.
Thus we have kept changelogs now for quite some time (actually years) of our applications under active development.
That is why our changelogs have gotten rather long and I was thinking about how to archive them "properly".
One issue with long changelogs in the Markdown format is that rendering them gets longer and longer, which could even lead to tool timeouts or unresponsiveness of the displaying tool.
Mentioning the major or major and minor version in the changelog, current or archived, can work well for projects adhering to SemVer.
For example, PHPUnit uses the changelog file name format
ChangeLog-x.y.md
but does not keep an archive, except for the ones in branches of previous release channels.https://github.com/sebastianbergmann/phpunit/blob/10.2.0/ChangeLog-10.2.md
https://github.com/sebastianbergmann/phpunit/blob/9.6/ChangeLog-9.6.md
But in our case, we adopted a non-SemVer-style versioning. We do not have major or minors but are date oriented (
YYYY-MM-DD
).Possible solutions:
CHANGELOG_ARCHIVED.md
file. Since it is an archive, it's not used that often, thus it doesnn't matter if it takes longer to load.CHANGELOG_2022.md
, in a (possibly) dedicatedchangelogs
folder. Whether splitting by full years is sensible depends on the project itself.Optionally, one could link from the main
CHANGELOG.md
to the archived ones.Other considerations:
Always keeping a single changelog file, such as
CHANGELOG.md
, even with archiving entries, just increases the commit history of the file. Which still can lead to longer loading time, e.g. when doing git blame or the like.Renaming and/or moving the current changelog file from
/CHANGELOG.md
to something/somewhere else keeps the git history of that file and its changelog entries.One can then create a new, current
/CHANGELOG.md
and stat anew.Anyway, I would propose to include some recommendations for hanlding/archiving large, long-running changelogs of projects (SemVer or not) in the FAQs of the standard.
Beta Was this translation helpful? Give feedback.
All reactions