> Both don't say much without good changelog. This is a good point. Good changelogs, like any documentation, take a lot of effort and so are unfortunately quit

> Both don't say much without good changelog. This is a good point. Good changelogs, like any documentation, take a lot of effort and so are unfortunately quite rare. As an API consumer, to me the ideal upgrade-related documentation includes: * Detailed release notes for each released version * For non-GA releases like alpha/beta/RC's, describe the changes since the last small release -- typically consumers of a beta are following dev quite closely * For GA releases, pretend the alpha/beta/etc don't exist at all. Describe the delta from the last GA release. Consumers don't care about the fix for a bug in a beta they never even knew existed. * When you do breaking changes, provide upgrade guidance, like "If you were doing x before, now you should do y + z instead" * If appropriate, consider also keeping separate upgrade guidance documentation for major breaking changes, for those laggard consumers that are going from a much older version like 2.x to 4.x. This allows someone to follow more of a checklist to get up-to-date without having to read 900 pages of individual release notes You can do this with date-based version, but it's much harder as a consumer to figure out unless there's very good documentation. If I'm upgrading from "2.0.4" to "4.1.1", I know as a absolute minimum starting point I will be looking at release notes for "3.0" and "4.0" and from that, I should get a pretty good sense of the overall effort involved. If I'm upgrading from "2016-11-05" to "2019-12-19", how do I do the equivalent evaluation?