Does anyone have an example of how they incorporat...

# library-development

[Matthew Pope]

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?

[Ignat Beresnev]

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

[Matthew Pope]

When do you incorporate the apiDump task?

[Ignat Beresnev]

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

[Ignat Beresnev]

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

[mbonnin]

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

[mbonnin]

If your CI calls build you should be covered

[Matthew Pope]

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.

[mbonnin]

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

[mbonnin]

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

[Ignat Beresnev]

@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

[Matthew Pope]

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.

[mbonnin]

That's weird. That part works for me

[Ignat Beresnev]

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

[Matthew Pope]

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.

[Matthew Pope]

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

[altavir]

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