practices
practices copied to clipboard
canonical-web-and-design
Changelogs
We cut our first release of the RBAC UI today, which led me down the path of looking into how to best format changelogs. I came across Keep a change log which seems like it provides some sensible advice.
I particularly like the idea of updating the [UNRELEASED] section with every MP/PR, which makes collating release notes almost trivial, for a small cost with each branch.
I came across Keep a change log which seems like it provides some sensible advice.
That's a set of good guidelines.
Most of our 'website' projects don't have versioned releases and doesn't keep a changelog (not sure if it would be useful to do). Maybe it would be a bit more useful for web applications (like snapcraft.io), but it also may be hard to keep with our "deploy at any time" policy. But for sure if a project has releases (like Vanilla does) it would be good to have some common practice to follow.
One thing that I'm missing in this article and would find interesting to have clarified (that was one of first questions I asked myself) - when to update changelog? Should new entry to "UNRELEASED" be added as part of every PR? And at the point of release there is a PR that creates new version and moves features into release (possibly cleaning up unnecessary changelog noice, adds notes about deprecation, etc)?
Should new entry to "UNRELEASED" be added as part of every PR? And at the point of release there is a PR that creates new version and moves features into release (possibly cleaning up unnecessary changelog noice, adds notes about deprecation, etc)?
Yep, I think that's the idea - a bit of an additional cost per PR, but would make release notes much easier.
Vanilla does not have a change log but does have release notes. This is difficult to see the development over many versions. :+1:
