Versioning & API Stability
Manage breaking changes and a public API contract.
Versioning & API Stability is a free Kotlin Multiplatform Academy lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Kotlin Multiplatform Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
A Version Is a Promise
When teams depend on your library, your version number tells them what to expect from an upgrade. Treat it as a contract, not a guess. 🤝
Semantic Versioning
SemVer uses three numbers: major, minor, and patch. Each part signals a different kind of change to anyone depending on your code.
version = "2.4.1"Patch for Fixes
Bump the patch number for backward-compatible bug fixes. Consumers can upgrade freely with no code changes on their side.
Minor for Features
Raise the minor number when you add new functionality without breaking anything. Old call sites keep working as before.
Major for Breaks
Increase the major number for any breaking change. This warns both teams that upgrading may require edits to their code.
Your Public API Is the Line
Stability is judged by your public surface. Renaming a public function breaks callers, but changing a private helper does not.
Hide What May Change
Mark unstable code internal so it stays out of the contract. You can refactor it freely without bumping the major version.
internal fun buildCache() { }Deprecate Before Removing
Give callers a soft landing with @Deprecated. They keep building, see a warning, and get told what to use instead.
@Deprecated("Use greet(name)")
fun greeting() = greet("there")Suggest a Replacement
Pair the deprecation with a ReplaceWith hint so the IDE can auto-fix old call sites. Migration becomes a single click.
@Deprecated("Renamed", ReplaceWith("greet(name)"))Watch for Accidental Breaks
Even reordering parameters can break Swift callers. Track your API with a dump tool so surprise changes get caught in review.
Keep a Changelog
A clear changelog lists what changed per version. Both Android and iOS teams plan upgrades with confidence instead of fear.
Quick Check
Let's check your versioning instincts.
Recap
Follow SemVer, guard your public API, hide unstable code as internal, deprecate kindly, and keep a changelog both teams trust. 🎉
Frequently asked questions
Is the “Versioning & API Stability” lesson free?
Yes — the full text of “Versioning & API Stability” is free to read here on the web, and the Kotlin Multiplatform Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Kotlin Multiplatform Academy course, upgrade to CoddyKit PRO.
What will I learn in “Versioning & API Stability”?
Manage breaking changes and a public API contract. You practise Kotlin Multiplatform Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Kotlin Multiplatform Academy?
No prior experience is required. Kotlin Multiplatform Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Versioning & API Stability” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Kotlin Multiplatform Academy lesson?
Yes. Every Kotlin Multiplatform Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Configure maven-publish for KMP
- Ship an XCFramework for iOS
- Versioning & API Stability
- Release to Maven Central & SPM