Versioning and upgrading
One version across ten ecosystems
Every core client carries the same number, deliberately. It means “generated from the same specification”, so two services in different languages can be reasoned about without a compatibility matrix.
A consequence: a client may release with no change of its own, because the version moved for another language or for a spec change that does not affect it.
What a major or minor bump can change
Below 1.0.0, a minor bump may break you. The things that move:
| Change | Why |
|---|---|
| Method names | An operation gaining an operationId renames its method |
| Model field names | A schema being typed where it was free-form |
| Return types | An untyped response becoming a typed model |
None of those is an API change. Your HTTP calls would be unaffected; your code does not compile.
0.3.0 is the example worth knowing
Every method was renamed. 80 operations had no operationId, so the
generator had been deriving names from routes, and giving them proper ids
renamed the lot: v1SendPost became sendEmail and so on throughout.
Nothing about the HTTP API moved. Callers using it directly noticed nothing. Callers on an SDK had to rename every call.
0.3.0 also broke two of the eleven clients outright, which is why
lockally-go@v0.3.0 must never be used: the Go module proxy is immutable, so
a published broken version can never be replaced, only superseded. That is
what 0.3.1 is.
Pin your version
"lockally": "0.3.3"
Pin exactly and upgrade deliberately. A caret range on a pre-1.0 package invites a minor bump to rename your methods during an unrelated deploy.
Upgrading
- Read the release notes before the diff. A renaming release says so.
- Bump in one place and compile. In typed languages the compiler finds nearly everything; in Python and Ruby your tests have to.
- Check field names, not just method names. A renamed model field fails
at runtime in dynamic languages, and an optional field quietly becomes
None. - Exercise one real send against a test key before deploying. It costs nothing and proves the path end to end.
For the 0.2 to 0.3 move specifically, including the full rename table, a grep that finds every affected call site, and the pin semantics that differ per ecosystem, see Migrating an SDK from 0.2 to 0.3.
CocoaPods is behind
Lockally on CocoaPods serves 0.3.1 while every other registry is on
0.3.3, after repeated publish failures. iOS callers are on older generated
code. It is a publishing fault, not an intentional difference, and not
something you can work around from your side.