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.
Usually those guides are finely scoped to specific components, but what if every library kept an upgrade guide that covered all aspects of the library?
This would be incredibly useful for consumers of the library if they fall behind by several releases, allowing them to follow the guide from version to version, making the required changes within their codebase.
I could imagine these guides being setup as a similar format as most
changelog.md files, broken down by release with detailed notes on how the
consumer can navigate any changes that the library is making.
This could also be a really useful resource for libraries that plan out their breaking changes, they can use this guide as a place to note upcoming breaking changes and how projects can plan for those changes before they are released.
What are your thoughts about this concept? Would you find it valuable for the
libraries you depend upon to ship a upgrade-guide.md document alongside their
existing changelog?
Tags:
Related Posts
Development
Published: ....
I recently launched a rewrite and redesign of this personal website, I figured I'd talk a bit about the changes and new features that I added along the way!
Published: ....
A quick tip outlining how to provide specific TypeScript type definitions for a local module!
Published: ....
Slicing software: why vertical is better than horizontal.
Published: ....
What if you could author an entire web application in a single file?
Published: ....
Is it a good or a bad thing to offload writing code to AI agents and Large Language Models?
Published: ....
A brief look at Import Maps and package.json#imports to support isomorphic JavaScript applications!
Published: ....
A collection of tech talks that I regularly re-watch and also recommend to everyone!
Published: ....
Some features and functionality that I'd like within a React Server Component compatible framework.
Published: ....
A (running) collection of Bluesky tips, tools, packages, and other misc things!
Published: ....
How to generate a custom Ghostty theme based on any iterm2 theme!
Published: ....
A rough mental model for how you should be leveraging AI as a tool for your own growth
Published: ....
Even more thoughts on dogfooding!
Published: ....
The secret to excellent product teams is using your own product, and often!
Published: ....
(Ab)using Git as yet another tool for thought!
Published: ....
A quick look at the applications and tools that I (generally) use day to day for web development!
Published: ....
There are a variety of different markdown "standards" out there, and sometimes they're not all that consistent
Published: ....
There's a common gotcha when creating Web Request and Response instances with Headers!
Published: ....
Feature toggles are often underused by most software development teams, and yet offer so much value during not only feature development but also refactors
Published: ....
A quick introduction to my new side project, hohoro. An incremental JS/TS library build tool!
Published: ....
webpack, and tools built on it like Next.js, don't support true dynamic imports, but I found a way to trick the system!
Published: ....
I've been using a variety of AI tools as of late, I figured I'd document the ones I'm primarily using!
Published: ....
I've started to use Cloudflare to manage my domains for several side projects, have had to jump through the same hooks multiple times that I figured I should document them here!
Published: ....
Revising my previous blog post on React Error Boundaries and my preferred go-to implementation!
Published: ....
Two neat tricks for enhancing your site's favicon!
Published: ....
The various risks and pitfalls of open source software run by corporations.
Published: ....
A monorepo template for managing a library and documentation together.
Published: ....
How we solved an almost show-stopping production bug, and how you can avoid it in your own projects.
Published: ....
When did semver major changes become so scary?
Published: ....
No I don't mean those Milano cookies you keep taking from the office snack wall either (although you should probably stop snacking on those as often as well).
Published: ....
Pair programming can be good sometimes - but not all the time
Published: ....
A few quick thoughts on burn out and taking a break