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.