Upgrade Guides

Published 📅: ....
Last modified 📝: ....

Share this post on BlueskySee discussion on Bluesky

Most healthy open source projects maintain a changelog, that annotates the changes made to the project over time, and usually relates those changes to the semver version that they are released with.

However, these changelogs tend to not go into details about how that change will impact projects relying on the library. Usually the changelog is just a convenience feature that allows people to track changes over time.

Something I've been thinking about for a while is if projects should offer either a more robust changelog, or a new file entirely that can better speak to the impact of changes made to the library over time.

The design systems team at Wayfair has been tinkering in this space for a few years now, usually when we deprecated a component or another piece of code we authored an upgrade guide or manual to help the features relying on the now deprecated component to move to the proper supported patterns.