Shall We Update API Libraries?

Summary When updating libraries, programmers must handle many compilation errors caused by API broken changes. It is difficult to resolve such errors, especially when new APIs typically have no code samples. The effort is explicit, but the benefits are hidden. Although new versions of libraries fix many bugs, library bugs may not affect the called APIs. As a result, many programmers are reluctant to update their libraries.In this project, we propose a tool to assist in deciding whether library bugs will affect a project. Our tool scans the source files of a project and compares library code. It can identify modified API methods and the commits that directly modify them. Result We evaluate our tool on the following project: Library Project Head jdk castorini/anserini 7302ce9d9e832d2d7158e3000973e1a99bf23a24 orientechnologies/orientdb ff68ae00cb6383a11eabc75991faf1a066b612f1 apache/jackrabbit ac9eecf375e7ea69b658b1d0635bb8eb33773b34 apache/jackrabbit-oak e60ad90e29a00cc829d4f0e48a807bb5e99443d9 neo4j/neo4j f4a030ab371744c779b0e34fd083f7004c4f65aa oracle/opengrok cb113bf7793565d9d5edec9406bed5f1c8bf1d9b inception-project/inception ee2a58b4ccca1be6073386ad738f7ab3909d94ec sepinf-inc/IPED b378c833ec35690f7387a0908c3580f9acb0ec14 apache/pinot 597f608a31fe9eda01b77d0cc604f18b71307afa spring-cloud/spring-cloud-kubernetes 464c06d58d50a46044ca6cc84377e6a2b2e54f75 mockito apache/cloudstack 4e61ddd1bcf2c72819fc8a99d6cdc83b74162b25 apache/shenyu 1aba81b7cad4916888f3b0decf3777e8ef23436b operaton/operaton a7658214004d85e6c87b6a88bdb8a680dde06bc8 ModelEngine-Group/app-platform 57b0222455e312dafd44c5df187e7e3d76bcaa21 apache/hertzbeat 0a48cf8f1324aeac90edeee4b3231797f902f9c0 spring-cloud/spring-cloud-kubernetes 464c06d58d50a46044ca6cc84377e6a2b2e54f75 AIDC-AI/Agentic-ADK 8222c282358923f2ab01cf85b4a05b950bef0e1e apache/bigtop-manager 0dc9b2fa4a9e2612458dc8c94a0be686495e324f binance/binance-connector-java b6e1fc6c1daba5aa46ffdae2f83402edf9a02fa8 apache/olingo-odata2 4d5418de2046be8bdc09b6e52d061c81c3c85a5f spring Finture/Flowee-BPMS 7e5837ce61d68f76652dc764f3a372f02414a848 oinone/oinone-pamirs f3957761c1042237c504c8e082968ccc5fa3c8e0 raedbh/spring-outbox 0f2afafb72715dde0bc44c78c0ee62fa79a0a521 HuLaSpark/HuLa-Server 8cdc3cf98c369ca4e7614c79e0ca404eb0ea31bf Tencent/spring-cloud-tencent 4d2ad436adb84a47d5ba6195d601dcf1e5c8adc9 camunda-community-hub/spring-zeebe 3fbf4e9d15e02a050c7903dda9919959be78730a taoofagi/easegen-admin 8f87936ac774065b92fb20aab55b274a6ea76433 operaton/operaton a7658214004d85e6c87b6a88bdb8a680dde06bc8 apache/dubbo 338d0181dd652637407a57b350495de260a761b9 risesoft-y9/DataFlow-Engine e6291947f51f047aea503d94075e5ce3de0df9bb gson wimoor-erp/wimoor 747b07bcfbb40748db71d0c9ee0d6fa561e0124d TileDB-Inc/TileDB-Client-Java c194f789a1d2eafb745757900048921dc2e3a5d1 essedum-project/essedum-platform 5a26e5e51d7561c70774ad0ae649eb4546a37406 microsoft/mssql-jdbc 7518254c136971c4726631fcbce7c0fb5247f5e7 MediaBrowser/Emby.SDK 2e43df69f7b28c4e81e43dc36ea3ab23f0459e7b AfterShip/shipping-sdk-java bcf90332365e6f8f4616771a91e67476c2e94f68 SZJM-GWMS/gwms-java-sdk b2063de771dabe889dcff4c41f40f21303195155 binance/binance-connector-java b6e1fc6c1daba5aa46ffdae2f83402edf9a02fa8 operaton/operaton a7658214004d85e6c87b6a88bdb8a680dde06bc8 Koekiebox-BV/Fluid 243c900985501f42219f270b20d77290a9e4d4e7 guice nuxeo/nuxeo 6392543ff4eac5b35627066d547123908b173871 helidon-io/helidon d31731dcd7dd7ff15be0bc0e481533235ed2c06e aws/aws-sdk-java 0561544011aec2712362d0b99bd0b86999f78a23 runtimeverification/k ae0245e1d20040e33436be2519c5db5d704ccac3 chsami/Microbot 0fbe025460e39ac5175b8cfc6ada0f8c1bba830b eclipse-xtext/xtext 2024890f690788b2387eda3046a3420f6c4cc2bb polardb/polardbx-sql c17e7eca8dedfe2f87268c0d6676a1adb9013168 eclipse-elk/elk c831ba4613dfd6b0055851193956560351d2f907 apache/ambari e92b1feab94ff37c2b0a7fd5ea1a67ec4d81aa23 apache/ozone ae4bdb30974f0ad5aa36024bbad770fab0901d35 lucene castorini/anserini 7302ce9d9e832d2d7158e3000973e1a99bf23a24 orientechnologies/orientdb ff68ae00cb6383a11eabc75991faf1a066b612f1 apache/jackrabbit ac9eecf375e7ea69b658b1d0635bb8eb33773b34 neo4j/neo4j f4a030ab371744c779b0e34fd083f7004c4f65aa oracle/opengrok cb113bf7793565d9d5edec9406bed5f1c8bf1d9b inception-project/inception ee2a58b4ccca1be6073386ad738f7ab3909d94ec evolvedbinary/elemental 4559adac5e18f47298263b8ecb40dc64b2efbcae hibernate/hibernate-search be220c7c57d22992d84ac71190f5dc81defe765a apache/pinot 597f608a31fe9eda01b77d0cc604f18b71307afa apache/jackrabbit-oak e60ad90e29a00cc829d4f0e48a807bb5e99443d9 zookeeper apache/bookkeeper 341f7d708423c38311239dda6d118e37aa9315bb ggj2010/javabase c3fcab1d26b3a4ffa1558115398d91b3a59d7b5e vespa-engine/vespa 907a1008b3c4cccdceec0600fa44f1724f14ccf3 didi/KnowStreaming 41b5f350f5da34ede618512be3354653e8781ddf apache/curator f18f0acf432231ece5dcd179020c4951dbe49803 apache/helix f1a5cd2a8dbdea54d818e00bd5828930a3141fe5 apache/pulsar feda88fa401af30886724310148c141007bf4bb0 apache/pinot 95d43c0d317cfd5d954e208e65cea5261a0aa571 sermant-io/Sermant 82436861b977c0575c892bc2e52c80b694ea332b zfoo-project/zfoo e6d35b0a7ec85a0e5af8fa1e45b0bc0341af9b92 To rebuild our checked projects, you can check out the above projects from Github and revert them to the listed head commit. The result directory contains our results. The directory of each project has four textual files. The callsite.txt lists the call sites. For example, an item is as follows:JSON.getDiscriminatorValue:com.google.gson.JsonObject.get(String)It denotes that the JSON.getDiscriminatorValue() method of the project calls the API method, com.google.gson.JsonObject.get(String). The call.txt lists unique called API methods. The modified.txt lists modified API methods. The update.txt lists the dumped details of modified API methods. We manually inspected update.txt. Our inspection results are listed at the end of each entry. For example, an entry is as follows: ----------------------------------------------------------------No com.google.gson.PrimitiveTypeAdapter.adaptType(Object,Class) edb60ad:2011-03-30 bling bling Prefix internal classes with $ to prevent them from interfering with IDE's auto import functionality. -other-5187808:2024-01-10, <--MyParameterizedTypeAdapter.deserialize It says that MyParameterizedTypeAdapter.deserialize calls the com.google.gson.PrimitiveTypeAdapter.adaptType(Object,Class) API method. This API method is modified by the edb60ad commit, whose message is ``bling bling Prefix internal classes with ...'' This modification does not affect the project since this modification fixes an issue with IDEs. As a result, we add our label, No, to this entry. If a project calls modified API methods, our tool dumps their revisions. The revisions are zipped in revision.rar. The tool is under the tool directory.