Does anyone have an example of how they incorporate the 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 Coroutines and serialization also use it extensively, I'm sure you can find examples if you look through their PRs

IIRC

apiCheck

is added as a dependency to

build

so you don't have much to do

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

@Matthew Pope 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

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.

That's weird. That part works for me

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

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.

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