You broke my code: understanding the motivations for breaking changes in APIs

As most software systems, libraries and frameworks also evolve, which may break existing clients. However, the main reasons to introduce breaking changes in APIs are unclear. Therefore, in this paper, we first report the results of an almost 4-month long field study with popular Java libraries and frameworks. We configured an infrastructure to observe all changes in these libraries and to detect breaking changes shortly after their introduction in the code. We detected possible breaking changes in 61 projects. After identifying breaking changes, we asked the developers to explain the reasons behind their decision to change the APIs. By analyzing the developers’ answers, we report that breaking changes are mostly motivated by the need to implement new features, by the desire to make the APIs simpler and with fewer elements, and to improve maintainability. To complement this first study, we describe a second study, including the analysis of 110 Stack Overflow posts related to breaking changes. We reveal that breaking changes have an important impact on clients, since 45% of the questions are from clients asking how to overcome specific breaking changes; they are also common in other ecosystems—JavaScript, .NET, etc. We conclude by providing suggestions to language designers, tool builders, software engineering researchers, and API developers.