But how do you deal with communicating that some library you maintain has a behavior change? People already need to know to look at your code in order to read your comments.

> communicating ... People

End users? Other Devs? These two groups are not the same.

As an end user of something, I dont care about the details of your internal refactor, only the performance, features and solutions. As a dev looking at the notes there is a lot more I want to see.

The artifact exists to inform about what is in this version when updating. And it can come easily from the commit messages, and be split for each audience (user/dev).

It doesn't change the fact that once your in the code, that history, inline is much much more useful. The commit message says "We fixed a performance issue around XXX". The inline comment is where you can put in a reason FOR the choice made.

One comes across this pattern a lot in dealing with data (flow) or end user inputs. It's that ugly change of if/elseif/elesif... that you look at and wonder "why isnt this a simple switch" because thats what the last two options really are. Having clues as inline text is a boon to us, and to any agent out there, because it's simply context at that point. Neither of us have to make a (tool) call to look at a diff, or a ticket or any number of other systems that we keep artifacts in.