Improved changelogs are coming your way

A recurring theme of feedback from the developer community relates to improving our communication, specifically around the announcement of API changes. To address this, the Developer Experience team has implemented a new solution for changelogs. In this post, I’ll outline the issues relating to our legacy approach to managing changelogs and what we’ve done to address these issues.

Over a year ago, we introduced internal guidelines relating to the formatting of changelogs so they are easy to consume. Since then, several teams have adopted this standard and have diligently maintained public changelogs. The Forge changelog and Confluence Cloud changelog are two examples of this.

Internally, however, changelog management has been rather simplistic and sub-optimal. Behind the scenes, a changelog is typically a markdown file that must be manually edited and reviewed in pull requests, etc. In addition, our cloud products are increasingly leveraging more and more platform components which means that a single change can often impact multiple APIs, and therefore multiple changelog files that are potentially in separate repositories, requiring multiple pull requests and reviews. Suffice to say, the legacy changelog maintenance process is labor intensive and not one that has been broadly adopted by development teams. As a result, we have several products and frameworks with substandard, and in some cases non-existent, changelogs.

To address this, the Developer Experience team has implemented a new solution for managing and publishing changelogs. Development teams can now enter changelog entries in a friendly WYSIWYG form, and enjoy a similarly friendly workflow for transitioning changelog entries through a review process before being publicly visible. Through the use of tagging, a single changelog entry can appear in multiple changelogs – no more duplicating content. The goal here is to reduce friction to ensure changelogs are comprehensive and adopted by additional products and frameworks.

The new solution also has a new rendering mechanism that yields user experience improvements. For instance, changelogs generated by the new solution are linked at the top of the relevant developer content section, allow for filtering of changelog items by type and subscription via RSS.

With the solution now in place, the Developer Experience team will be advocating internally for further adoption. We are also intending to introduce improvements, such as:

  • Filtering and pagination usability improvements
  • Adding support of deep linking to changelog items (shipped: see below )
  • Badging changelog links with the number of unread items in the changelog
  • Internal process improvements to further reduce the friction required to manage changelog information

The Forge changelog has already been migrated to the new solution so please take a look and let us know what you think.

16 Likes

Happy to hear there is progress being made. Maybe productize this like Statuspage :wink:

Is this why the Forge one has an RSS feed and Confluence Cloud does not?

2 Likes

Hi @boris , yes, the RSS feed will only appear on the new changelogs. I’ve done much of the preparation for Confluence Cloud’s onboarding to the new changelog solution so hopefully it won’t be long before it is fully onboarded. cc @ElaineH

4 Likes

Is there also another option to actively watch the changelog pages? Or is that the intention behind the RSS feed that we can subscribe to that to stay up to date?

1 Like

Hi @matthias, yes, that was the intention of the RSS feed. We realise that it’s not an ideal mechanism, but it was relatively simple to implement. Happy to hear your thoughts on its adequacy and other ideas you have. Regards, Dugald

2 Likes

I guess, the RSS feed should work - we’ll probably hook it up with a channel in our company slack to stay up to date.

4 Likes

Shameless plug - may be look at Automated release notes for Jira? Cloud version even has what we call ‘release page’.
:grimacing:

As an update, we have now added the ability to deep link to specific changelog items. Click the :link: icon next to each changelog title to copy the URL. When navigating to that URL, the changelog will change to the correct page no. and highlight the desired item. Even if the item gets pushed to a higher page no. in future, the link will still work.

Please note that these links are not backwards-compatible with old changelog deep-links. If you have any changelog links that point to a specific item, please update them.

4 Likes

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.