What we compared
For each library we took the last few stable releases from Maven Central and compared every AAR with the one before it: the classes in classes.jar, minSdkVersion in the manifest, and the resources listed in R.txt.
| Release | Class changes that break callers | minSdk |
|---|---|---|
| Lottie 6.6.10 → 6.7.0 → 6.7.1 | 0, 0 | 16 (unchanged) |
| Glide 5.0.7 → 5.0.9 | 4 | 14 → 23 |
| Glide 5.0.9 → 5.0.10 | 7 | 23 |
| Calendar (view) 2.9.1 → 2.10.0 → 2.10.1 | 0, 0 | 21 → 23, then 23 |
| Koin (koin-android) 4.1.1 → 4.2.0 → 4.2.1 | 0, 0 | 21 → 23, then 23 |
| Balloon 1.7.5 → 1.7.6 | 0 | 23 (unchanged) |
Most releases changed no public classes in a way that breaks callers. Three raised minSdk, which no class comparison shows, and some of Glide's class changes are in a class its own release notes call internal.
1. Raising minSdk
Glide 5.0.9 raised minSdkVersion from 14 to 23. The previous release on Maven Central was 5.0.7, so for anyone upgrading, this happened in a patch release. Glide announced it in the 5.0.8 notes: "Bump Glide minSdkVersion to 23 to match AndroidX requirements", under Build Changes. (5.0.9 is the same release with a fixed version name, and 5.0.8 never reached Maven Central.) Calendar 2.10.0 and Koin 4.2.0 raised it from 21 to 23 in minor releases.
An app with a lower minSdk that takes the upgrade stops building. The manifest merger in the Android Gradle Plugin fails with:
uses-sdk:minSdkVersion 21 cannot be smaller than version 23 declared in library [com.github.bumptech.glide:glide:5.0.9]
as the library might be using APIs not available in 21
Suggestion: use a compatible library with a minSdk of at most 21,
or increase this project's minSdk version to at least 23,
or use tools:overrideLibrary="com.bumptech.glide" to force usage (may lead to runtime failures)
The build failure is easy to see. An app that can't raise its own minSdk is then stuck on the old version and misses every fix after it. Glide 5.0.10 has a security fix (sensitive headers are now stripped on cross-origin redirects), and an app on minSdk 21 can't take it without dropping devices.
Instead: treat a minSdk raise as a change your users have to act on. Many libraries do it in a minor release, which is fine if it's the first line of the release notes and not something people find out from a failed build. Doing it in a patch release surprises the people who pin to patch updates precisely because they expect nothing to change.
2. Public classes you think of as internal
Glide 5.0.9 made three public classes final, among them Engine and ViewPreloadSizeProvider. Glide 5.0.10 changed three public methods of Engine to take an EngineKey instead of a Key, and removed DiskLruCacheWrapper.create(File, long, boolean), which 5.0.9 had added already marked @Deprecated. Glide's 5.0.10 notes describe the Engine change as narrowing "internal" tracking keys.
From Glide's side, that's fair: nobody is supposed to subclass Engine. But an app or another library only sees public class Engine with public methods. Nothing in the bytecode says "internal", so code that did subclass or call it compiled without a warning and breaks on the upgrade:
java.lang.NoSuchMethodError: 'com.bumptech.glide.load.engine.cache.DiskCache
com.bumptech.glide.load.engine.cache.DiskLruCacheWrapper.create(java.io.File, long, boolean)'
That's a client compiled against 5.0.9 and run with 5.0.10 on the JVM. On a device, ART reports the same missing method in its own wording.
Instead: mark the boundary in the code, where users and tools can see it:
- In Kotlin, use
internal. It's still public in the bytecode, but other modules can't call it from Kotlin. - Annotate with
@RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)fromandroidx.annotation. Android Lint'sRestrictedApicheck then flags any use outside your library group, and it runs by default in Android projects. - Keep implementation classes in a package with "internal" in its name, so users and tools can tell them apart.
3. "But apps recompile anyway"
On Android, the app is rebuilt from source every time, so it can look as if only source compatibility matters. But the app isn't the only code that uses your library. Other libraries in the same app were compiled against the version of yours that they were built with, and they aren't recompiled. Gradle picks one version of your library for the whole app, usually the highest one requested. If another library was built against Glide 5.0.9 and calls DiskLruCacheWrapper.create(File, long, boolean), an app that also pulls in Glide 5.0.10 compiles fine and gets the NoSuchMethodError above at runtime, on the user's phone.
Kotlin makes this easy to trigger. Adding a parameter with a default value keeps every caller's source working, but changes the compiled signature:
// 1.0
fun show(month: YearMonth)
// 1.1
fun show(month: YearMonth, animate: Boolean = false)
An app that calls show itself just compiles against 1.1. A library compiled against 1.0 still calls the one-parameter version, which no longer exists. (This is an example, not a change from the libraries above.) Adding a property to a public data class breaks callers the same way. Both are covered, with the real errors, in Seven Kotlin changes that pass your build and break your users.
Instead: keep the old signature as an overload marked @Deprecated(level = DeprecationLevel.HIDDEN) that calls the new one. Old binaries find it, and new code can't see it.
4. Resources are public unless you say otherwise
The Android documentation says: "All resources in a library default to public." Every layout, string, drawable and attribute in your AAR can be used by the app as R.<type>.<name>, and renaming or removing one breaks the apps that used it. Once you declare at least one resource public in res/values/public.xml, all the others become private. Android Studio then leaves them out of code completion, and Lint warns when an app uses one anyway.
In our sample, Lottie 6.7.1 and Calendar 2.10.1 ship no public.txt, so all 32 and 28 of their resources are public. Balloon 1.7.6 declares 12 public resources and keeps the rest private. None of the releases we compared removed a resource.
Instead: add a public.xml listing the attributes and styles users are meant to set. A single <public /> tag with no name makes every resource private.
The four at a glance
| Change | What the app sees | Instead |
|---|---|---|
Higher minSdk | Manifest merger fails | First line of the release notes; not in a patch |
| Changed "internal" public class | Compile error, or NoSuchMethodError in another library | internal, @RestrictTo |
| New parameter with a default | NoSuchMethodError in libraries built against the old version | Hidden deprecated overload |
| Renamed or removed resource | Unresolved R reference | public.xml |
How to catch them
- Binary compatibility validation in the Kotlin Gradle plugin (experimental), or the older binary-compatibility-validator plugin, now in maintenance mode. Both write your public API to a file you commit and fail the build when it changes unexpectedly.
- Lint's
RestrictedApicheck, once your internal classes carry@RestrictTo. - Bumpwise: our plugin for Android Studio and IntelliJ IDEA. It downloads the AAR of your last release, compares it with your code and highlights the changes that break it while you type, with quick fixes such as the hidden overload above. It checks classes only: it doesn't compare
minSdkor resources yet. To leave classes out, add their package or an"@androidx.annotation.RestrictTo"entry toexcludein.bumpwise.yml.
Disclosure: Gilware makes Bumpwise. It's free for Java libraries on Maven Central; Kotlin support is part of Bumpwise Team, the paid edition, which has a 30-day free trial.
How we checked
On 20 November 2026 we downloaded each AAR from Maven Central and compared the classes with the Bumpwise engine. We then checked every reported change by hand with javap, read minSdkVersion from each AAR's AndroidManifest.xml, and counted resources from R.txt (styleable entries left out). The manifest merger message is the one in the Android Gradle Plugin's manifest merger. Release notes are quoted from each project's GitHub releases. The NoSuchMethodError comes from a small client compiled against Glide 5.0.9 and run with 5.0.10 (OpenJDK 25).
Found a mistake? Write to hello@gilware.com.