Schema Versioning

[swankjesse]

Schemas change over time. We need to design a safe way for composers and displays to interop safely if their schemas are on different versions. We should also consider tools to help prevent unexpected incompatible schema changes.

I recommend we enforce that the composer code is never older than the display code. Supporting forwards and backwards compatibility is way harder than just backwards compatibility. Developers are already familiar with only backwards compatibility; servers are never older than their clients. If the composer code is too old, we get new code by either updating dependencies (build time) or downloading (runtime).

I recommend we require explicit schema versions. I think a single integer like Android API versions should be enough. I don’t expect we’ll ever want to change schema version 3 after schema version 4 is created. We can make the schema version an attribute of the @Schema annotation, and build some process or mechanism to remind people to bump this.

I recommend we make the display’s version available to the composer so it can fall back. For example, a composer could emit a stock price to a TextLabel if the display doesn’t support a StockChart node.

To prevent unexpected schema versions we could generate a JSON representation of the schema as a project resource, generated when we generate code. The Gradle plugin could check whether the JSON representation of the current project is compatible with another version. We do this with japicmp in Okio and it’s saved us enough times to be worth the investment.

[JakeWharton]

I would not choose JSON since it diffs quite poorly. Simple plain text with indents (similar to metalava in AndroidX or the binary validator by Kotlin) or YAML/TOML diff well in comparison.

Otherwise this sounds exactly like what I had in mind.

[JakeWharton]

Ideas from meeting with Eric:

• Reuse Android Lint which is a general-purpose Kotlin code linter and already has checks such as NewApi which handle conditional control flow gated on version checks.
• Generate a compatible manifest from your schema as part of our Gradle plugin in the form the NewApi check requires
• Run lint over your composables and with the schema manifest as an input (the schema itself is already an input so it can ride along with that) so that the check validates at runtime version requirements.

Note that this is different than runtime querying but not entirely separate from it as runtime querying should also be considered a valid conditional to suppress the check.

[JakeWharton]

This also requires no version annotations directly in the schema. Instead for each version you update the schema manifest which adds all new widgets and the associated version but retains all the old version history.