Every Release Note Is a Lesson Somebody Paid For

There is a free, expertly written, continuously updated course on almost every tool you use, and hardly anyone opens it. It is the release notes.

Think about what goes into one. A maintainer, who understands that system better than you ever will, sat down and wrote the shortest possible description of what changed and why it mattered enough to change. Every deprecation in that list is somebody saying this turned out to be a mistake. Every breaking change is a design decision being corrected in public. Every security fix is a failure mode, described precisely, by the person who fixed it.

That is a long way from a tutorial, and it teaches something tutorials cannot. Tutorials show you the happy path as it looked on the day they were written. Release notes show you where the edges are and how the thing moves.

The habit is small. Pick three or four things you genuinely depend on. Your language runtime, your web framework, the database driver, the CI system. Subscribe to their releases, or put a fifteen minute slot in your calendar once a month and go through them then. Skim the whole list, slow down on anything under breaking changes or deprecations, and pick exactly one item that surprises you. Follow it to the issue or pull request behind it and read the argument. That one thread will teach you more about how the tool thinks than an afternoon of documentation.

Read the upgrade guide even when you are not upgrading. It is the clearest description anyone will ever write of what the old design got wrong.

You will also start recognising your own bugs in other people's changelogs, which is a strange and useful feeling. Fixed a case where connections were not returned to the pool after a timeout. You have met that bug. You lost a day to it. Now you know it had a name and a number.

Do not try to read everything, and do not feel bad about the weeks you skip. Fifteen minutes a month on four repositories is already more than most engineers do, and after a year you will sound like someone who has been paying attention. You will have been.

– Asael Shinder