search

canonical-web-and-design / practices

Guides and principles from the web team at Canonical and Ubuntu
https://canonical-web-and-design.github.io/practices/
Other
45 stars 30 forks source link

Changelogs #149

Open squidsoup opened 5 years ago

squidsoup commented 5 years ago

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.

bartaz commented 5 years ago

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)?

barrymcgee commented 5 years ago

The Juju GUI already uses this approach.

squidsoup commented 5 years ago

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.

squidsoup commented 5 years ago

The Juju GUI already uses this approach.

Excellent!

nottrobin commented 5 years ago

:+1:

anthonydillon commented 5 years ago

Vanilla does not have a change log but does have release notes. This is difficult to see the development over many versions. :+1: