3 ms·

Both don't say much without good changelog. But with semver you can say: ok, I want every new version up to a new minor version (all fixes). While with a date

by thdrdt 7y ago

Both don't say much without good changelog. But with semver you can say: ok, I want every new version up to a new minor version (all fixes). While with a date based version you don't know how 'breaking' the changes will be.

keithwhor 7y ago
How often do you feel like you find / consume changelogs when you’re looking at APIs? I feel like they’re either non-existent or non-obvious for most SaaS companies. Do you feel like you’d trust a company’s API more if you could peruse the API changelog more easily?
- thdrdt 7y ago
  It's not about trusting a company. It's about wanting to know what will break if you start using a newer version of an API. And sometimes you also discover new features that can be really useful.
  - keithwhor 7y ago
    That’s fair! From my perspective that’s something that’s building trust with the SaaS provider. We’ve all heard, “ugh! This API is so shitty!” before — I’m fascinated by what tools and products can be built to prevent developers from feeling these pains. Thanks for the feedback. Can definitely see that changelogs are really underinvested in across the industry, and it’s useful to have people mention how valuable they are.
k__ 7y ago
I never understood why we settled on semver. If I have a bug, it's a breaking change. If I fix this bug, it's also a breaking change.
- tclancy 7y ago
  Your presumption of a collective "we" is at the root of the problem: versioning is one of those things in development where the same word can mean very different things to different people (see also: agile, automated testing). Prior to semantic versioning, there was an approach that looked like an agreed-upon standard to consumers of software packages/ libraries/ APIs but was not. On one extreme you had certain developers (who I am sympathetic to because it's my personality) who were loath to ever label something 1.0 because it implies Doneness and a freedom from bugs that can never be so. On the other side you had people at chop shops who would bump the major version of some boxed product every time they fixed two bugs. Even if you as a good developer did the research to discover that 0.7.6 of Package A was solid and 5 years older than Package B 7.6, there was a good chance someone above you would declare 7.6 > 0.7.6 and that it was paid-for software so "We can get support from them" and force you to work with a shittier product. So "we" developers do what we almost always do: we cast about for a better solution and landed on one that made the meaning of version numbers opaque to anyone outside the guild of mages writing code. In short, semantic versioning may suck hard, but it sucks less.
  - k__ 7y ago
    True. Semver is like unsound type systems or TDD, most of the time it's okay, until it isn't.
gregmac 7y ago
> 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?

by thdrdt 7y ago

keithwhor 7y ago

How often do you feel like you find / consume changelogs when you’re looking at APIs? I feel like they’re either non-existent or non-obvious for most SaaS companies. Do you feel like you’d trust a company’s API more if you could peruse the API changelog more easily?

thdrdt 7y ago
It's not about trusting a company. It's about wanting to know what will break if you start using a newer version of an API. And sometimes you also discover new features that can be really useful.
- keithwhor 7y ago
  That’s fair! From my perspective that’s something that’s building trust with the SaaS provider. We’ve all heard, “ugh! This API is so shitty!” before — I’m fascinated by what tools and products can be built to prevent developers from feeling these pains. Thanks for the feedback. Can definitely see that changelogs are really underinvested in across the industry, and it’s useful to have people mention how valuable they are.

k__ 7y ago

I never understood why we settled on semver. If I have a bug, it's a breaking change. If I fix this bug, it's also a breaking change.

tclancy 7y ago
Your presumption of a collective "we" is at the root of the problem: versioning is one of those things in development where the same word can mean very different things to different people (see also: agile, automated testing). Prior to semantic versioning, there was an approach that looked like an agreed-upon standard to consumers of software packages/ libraries/ APIs but was not. On one extreme you had certain developers (who I am sympathetic to because it's my personality) who were loath to ever label something 1.0 because it implies Doneness and a freedom from bugs that can never be so. On the other side you had people at chop shops who would bump the major version of some boxed product every time they fixed two bugs. Even if you as a good developer did the research to discover that 0.7.6 of Package A was solid and 5 years older than Package B 7.6, there was a good chance someone above you would declare 7.6 > 0.7.6 and that it was paid-for software so "We can get support from them" and force you to work with a shittier product. So "we" developers do what we almost always do: we cast about for a better solution and landed on one that made the meaning of version numbers opaque to anyone outside the guild of mages writing code. In short, semantic versioning may suck hard, but it sucks less.
- k__ 7y ago
  True. Semver is like unsound type systems or TDD, most of the time it's okay, until it isn't.

gregmac 7y ago

> 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?