Is there a way to break API less often?

[vlsi]

Expected Behavior

The users should be able to upgrade ktlint without waiting for the re-implementation of the build system plugins.

Observed Behavior

Almost all the recent ktlint releases break backward compatibility one way or the other.

For instance:

• StandardRuleSetProvider.get() disappeared in 0.45.0
• KtLint plugin failed to load reporter plain with Ktlint 0.49.0 JLLeitschuh/ktlint-gradle#665 fails to work with 0.49.0
• spotless fails to work with 0.49.0 as well:

                    Caused by: java.lang.reflect.InvocationTargetException
                        at com.diffplug.spotless.kotlin.KtLintStep$State.createFormat(KtLintStep.java:132)
                        at com.diffplug.spotless.FormatterStepImpl$Standard.format(FormatterStepImpl.java:80)
                        at com.diffplug.spotless.FormatterStep$Strict.format(FormatterStep.java:88)
                        at com.diffplug.spotless.Formatter.compute(Formatter.java:246)
                        ... 89 more
                        Caused by: java.lang.NoClassDefFoundError: com/pinterest/ktlint/core/api/editorconfig/CodeStyleEditorConfigPropertyKt
                            at com.diffplug.spotless.glue.ktlint.compat.KtLintCompat0Dot48Dot0Adapter.<clinit>(KtLintCompat0Dot48Dot0Adapter.java:58)
                            at com.diffplug.spotless.glue.ktlint.KtlintFormatterFunc.<init>(KtlintFormatterFunc.java:43)
                            ... 93 more
                            Caused by: java.lang.ClassNotFoundException: com.pinterest.ktlint.core.api.editorconfig.CodeStyleEditorConfigPropertyKt
                                at java.base/java.net.URLClassLoader.findClass(URLClassLoader.java:476)
                                at com.diffplug.spotless.FeatureClassLoader.findClass(FeatureClassLoader.java:79)
                                at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:589)
                                at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:522)
                                ... 95 more

As you might see, spotless has compatibility layers for several ktlint versions already: https://github.com/diffplug/spotless/tree/main/lib/src
It likely means none of the upgrades were possible without corresponding changes in spotless.

Steps to Reproduce

plugins {
    id("com.diffplug.spotless") version "6.18.0"
    kotlin("jvm") version "1.8.20"
}

spotless {
    kotlin {
        ktlint("0.49.0")
    }
}

Your Environment

Gradle 7.3, ktlint 0.49.0

[paul-dingemans]

Last year we have refactored our entire API to make it future proof. This of course has proven to be challenging for our API consumers and you not the only one who has voiced this complaint. But the good news is, as was also announced in the changelog:

This release is intended to be the last release before the 1.0.x release of ktlint. If all goes as planned, the 1.0.x release does not contain any new breaking changes with except of removal of functionality which is deprecated in this release.

The idea is that with 1.0 the API will become stable for a series of releases. It means that starting from 1.0 the focus will shift to implementation of rules instead of changes in the API.

[Note: Issue is kept open as reference for others although nothing will be changed in next releases to accomodate for this]

[paul-dingemans]

In #2131 the binary compatibility validatior has been added as well. It will help up us to protect against accidental API changes.

Although 1.0 contains a few minor breaking API changes, I expect that the API will be stable with 1.0 release. Currently, the backlog does not contain any open issue for which an API change will be needed.