A modern programming language that makes developers happier.

kotlinlang

Does anyone have an example of how they incorporate the <https://github.com/Kotlin/binary-compatibility-validator|binary compatibility validator plugin> in a CI workflow? I get how to run it, but I'm not sure when it should be run. Pre-release? Every build? Something else? What has worked for you?

apiCheck on every commit in a PR seems to work (so every build)

When do you incorporate the `apiDump` task?

You don't. Afaik it's usually run manually when you've made some changes, and then you commit whatever it generates within the same PR. Reviewers can then comment on it as well

At least that's how we do it, have a look at this PR for instance: <https://github.com/Kotlin/dokka/pull/2496|https://github.com/Kotlin/dokka/pull/2496>

Coroutines and serialization also use it extensively, I'm sure you can find examples if you look through their PRs

Here's an example from coroutines, a year old but still: <https://github.com/Kotlin/kotlinx.coroutines/pull/2721|https://github.com/Kotlin/kotlinx.coroutines/pull/2721>

IIRC `apiCheck` is added as a dependency to `build` so you don't have much to do

If your CI calls `build` you should be covered

I guess my confusion is that if you include the output of `apiDump` in the PR, then the `apiCheck` task is questionably useful because it will always pass because you're always regenerating the baseline API to whatever you are committing. If you do not include the `apiDump` in the PR, then you don't have a clear way to re-baseline the API checks.

Yea but it still gives you a single place to watch out for changes to your public APIs

I'd love to have `./gradlew apiDumpSafe` that fails on breaking changes but that looks pretty hard to do: <https://github.com/Kotlin/binary-compatibility-validator/issues/70>

<@U017ZD5AQT1> apiCheck will fail if you unintentionally make existing API incompatible, which is way easier than it sounds :) It will also fail if you accidentally expose something as public API without noticing - also happens sometimes, especially in large PRs

If the changes were intentional, you run apiDump manually and it will add/change some lines in the .api files, you basically acknowledge that you want it

These files also give reviewers an easy way to watch for public API changes, especially useful in large PRs or when you have a bunch of modules and only a number of them are public

&gt; It will also fail if you accidentally expose something as public API without noticing
I don't think it does. I just tested it out by adding a new public function to my library, and `apiCheck` passed even without updating the api dump.

Yeah, it's supposed to fail. Again, have a look at commits here, you can see that the build failed because the contributor forgot to run apiDump

<https://github.com/Kotlin/dokka/pull/2496|https://github.com/Kotlin/dokka/pull/2496>

Oh, I figured out the problem. I tested it using an inline function with a reified type parameter. When I test it with a simple function (eg. `fun foo() = 1`) then `apiCheck` catches it.

Okay. If `apiCheck` fails on additive changes, then it all makes sense.

I've also added bypass on checks for snapshot/dev versions