Why use the `.api` extension and not `.abi`?

Kotlin / binary-compatibility-validator

Public API management tool

Apache License 2.0

759 stars 55 forks source link

Why use the `.api` extension and not `.abi`? #198

Open joffrey-bion opened 3 months ago

joffrey-bion commented 3 months ago

Given that these files are meant to represent a serialized ABI to check binary compatibility, and that the tool is called binary-compatibility-validator it would make sense to call this the ABI, right?

qwwdfsad commented 3 months ago

It indeed makes sense. This is rather a historical oddity where we first started with "what is public API" and then every other name just followed. If we ever consider pushing BCV to 1.0 or merging it into Kotlin upstream, we definitely should consider the renaming

joffrey-bion commented 3 months ago

I see, thanks. I was thinking that maybe because of the change in structure with the klib / KMP support, it might be a good time to change the extension too

fzhinkin commented 3 months ago

We thought about that too, but changing the name of JVM dump files would be painful for existing users, and having two files (for KLib and class files) with the (conceptually) same stuff inside but different names looked weird.

joffrey-bion commented 3 months ago

changing the name of JVM dump files would be painful for existing users

In which way?

These files are updated each time an ABI change happens, so it's already part of the process to update them/commit them in some way. Making a source code change + apiDump + commit is as complicated as making a plugin version update + apiDump + commit. Git is quite good at recognizing the file even with a different name if the contents don't change. Is there something I am missing?

fzhinkin commented 3 months ago

In which way?

If we change the file extension name, plugin's update in a project will make the dump invalid (well, the dump will not exists from plugin's POV) even if nothing had changed in the ABI;
git --follow helps with renaming, but it's not something working out of the box.

Given that the new release introduces experimental feature useful for some developers (those who owns KMP projects), it's hard to justify why everyone else should be disturbed.

As Vsevolod said, it's something that could be done with a major release, but for now we decided to stick to existing naming convention.

joffrey-bion commented 3 months ago

plugin's update in a project will make the dump invalid

Yes, and the good thing about it is that it's a conscious decision, so nothing surprising to the users here. It has happened several times in the past that updating the Kotlin plugin breaks the dumps (which is arguably more surprising), and at least for me personally it has never been more painful than forgetting to apiDump after a code change.

Also, enabling the klib support flag (which I guess one day will be the default) already moves the dumps, so we may as well capitalize on this :)