Skip to content

API compatibility and versioning

Katari encodes an extension's API family and its own revision in the APK versionName. The SDK artifact tag is a separate value.

Value Example Meaning
APK versionName 2.0.3 Entry API family 2.0, extension revision 3
APK versionCode 13 Android's monotonically increasing update number
SDK dependency sdk-2.0.1 Exact published entry-source-api artifact used to compile

The final components in sdk-2.0.1 and extension versionName = "2.0.1" happen to match in the initial release, but they do not have the same meaning. A later extension release can use versionName = "2.0.4" while still compiling against sdk-2.0.1.

Select an SDK

Use a tagged SDK in published builds:

compileOnly("com.github.kiryl-kvit.katari:entry-source-api:sdk-2.0.1")

Use local-SNAPSHOT only while testing coordinated changes against a local Katari checkout. The dependency remains compileOnly because Katari supplies the API and runtime implementation. Bundling the SDK in an extension can create duplicate, incompatible classes.

An SDK patch tag can add fixes or compatible APIs without changing the loader family. Compiling successfully does not by itself prove that every Katari release in the family contains a newly added API. If an extension uses a symbol introduced by a newer SDK, it also requires a Katari version that supplies that symbol at runtime.

Encode the loader family in versionName

Entry-native extensions currently use the 2.0 family. Encode it in the first two components and use the last component as that extension's revision:

android {
    defaultConfig {
        versionCode = 4
        versionName = "2.0.4"
    }
}

For an installed APK without separate library metadata, Katari removes the final component and validates the resulting 2.0 family before loading extension classes. The Katari extension repository also publishes extensionLib by removing the final component from the APK's versionName. Consequently, a value such as 1.3.0 would be interpreted as API family 1.3, not as extension release 1.3.0.

The APK loader can read explicit tachiyomix.extensionLib metadata for compatibility with other packaging schemes, but Katari's extension authoring and repository workflow expects the structured versionName. Do not use explicit metadata to give a Katari extension an unrelated version scheme.

The current loader accepts the Entry 2.0 family. It also has separate compatibility paths for selected legacy Mihon API families; those paths do not make legacy source-api the authoring API for new extensions.

Compatible and incompatible changes

Within a compatibility family, extension authors should still treat these changes cautiously:

  • Calling a newly added API requires an app release that implements it.
  • Removing or changing a public method, model field, constructor, or serialized meaning can require a new family.
  • Moving public classes between packages is a binary compatibility break.
  • Changing either of the first two versionName components changes the declared API family.
  • Changing source IDs or content URLs is a data-identity change even when binary compatibility is unaffected.
  • Changing Android minimum API requirements can exclude devices independently of Entry API compatibility.

Adding an optional capability interface is useful only when the installed Katari version recognizes it. Provide a reasonable baseline behavior when the core UnifiedSource contract permits one.

Upgrade workflow

When adopting a newer SDK:

  1. Read the SDK release notes and inspect the public contracts your extension uses.
  2. Update the tagged compileOnly dependency.
  3. Keep the first two components of versionName at 2.0 unless the SDK release explicitly introduces another family.
  4. Compile and test against the oldest Katari release you intend to support.
  5. Test against the current Katari release.
  6. Increase the final component of versionName, publish with a higher APK versionCode, and preserve the package and signing identity.

If the extension must use a newly introduced symbol, state the minimum Katari version in its release notes or repository metadata. Do not claim support for older app releases based only on the shared 2.0 family label.

Local SDK development

For a coordinated API change, publish the local modules:

./gradlew --quiet :core:common:publishToMavenLocal :entry-source-api:publishToMavenLocal

Then add mavenLocal() to the extension build and use local-SNAPSHOT. Before publishing the extension, return to a tagged SDK and verify the build again. See publishing and maintenance for the complete release checklist.