Skip to main content
SpringerLink
Log in

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

  • Published:
Empirical Software Engineering Aims and scope Submit manuscript

Abstract

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.

This is a preview of subscription content, log in via an institution to check access.

Access this article

Log in via an institution

Price excludes VAT (USA)
Tax calculation will be finalised during checkout.

Instant access to the full article PDF.

Fig. 1
Fig. 2
Fig. 3
Fig. 4
Fig. 5
Fig. 6
Fig. 7
Fig. 8
Fig. 9
Fig. 10
Fig. 11
Fig. 12
Fig. 13
Fig. 14
Fig. 15
Fig. 16
Fig. 17

Similar content being viewed by others

Notes

  1. https://search.maven.org/stats

  2. Currently, apidiff does not detect breaking changes in annotations. Instead, these breaking changes are reported in the fields of the interfaces defining an annotation.

  3. https://github.com/libgdx/libgdx/commit/3eede16

  4. https://github.com/facebook/fresco/commit/f6fe6c3

  5. Most cases refer to internal or low-level API (34 occurrences) and one is an accidental change.

  6. In the case of fields, breaking changes occur mainly when changing the type or default value of a public field (or when removing it).

  7. https://stackoverflow.com/company

  8. https://meta.stackoverflow.com/questions/tagged/closed-questions

  9. https://stackoverflow.com/questions/35233989

  10. https://data.stackexchange.com/help

  11. https://stackoverflow.com/questions/8929130

  12. https://stackoverflow.com/questions/15543841

  13. https://stackoverflow.com/questions/48854954

  14. https://stackoverflow.com/questions/1456785

  15. https://stackoverflow.com/questions/19638981

  16. https://stackoverflow.com/questions/2678744

  17. The users profile are unclear in 8 questions classified as general discussions.

  18. https://stackoverflow.com/questions/35993598

  19. https://stackoverflow.com/questions/32442605

  20. https://stackoverflow.com/questions/32151603#32151901

  21. https://stackoverflow.com/questions/45725330#45743449

  22. https://stackoverflow.com/questions/12137939

  23. https://stackoverflow.com/questions/27243

  24. https://stackoverflow.com/questions/8279299

  25. https://stackoverflow.com/questions/19315263

  26. https://stackoverflow.com/questions/30300279

  27. https://stackoverflow.com/questions/39533030

  28. https://stackoverflow.com/questions/38985159

  29. https://stackoverflow.com/questions/44642302

  30. https://stackoverflow.com/questions/1456785

  31. https://stackoverflow.com/questions/19614954

  32. https://stackoverflow.com/questions/19638981

  33. https://github.com/siom79/japicmp

  34. https://github.com/aserg-ufmg/apidiff

References

  • Abdeen H, Ducasse S, Sahraoui H, Alloui I (2009) Automatic package coupling and cycle minimization. In: 16th working conference on reverse engineering (WCRE), pp 103–112

  • Ahasanuzzaman M, Asaduzzaman M, Roy CK, Schneider KA (2018) Classifying Stack Overflow posts on API issues. In: 25th international conference on software analysis, evolution and reengineering (SANER), pp 244–254

  • Anquetil N, Lethbridge TC (1999) Experiments with clustering as a software remodularization method. In: 6th working conference on reverse engineering (WCRE), pp 235–255

  • Bajaj K, Pattabiraman K, Mesbah A (2014) Mining questions asked by web developers. In: 11th working conference on mining software repositories (MSR), pp 112–121

  • Barua A, Thomas SW, Hassan AE (2014) What are developers talking about? an analysis of topics and trends in Stack Overflow. Empirical Software Engineering 619–654

    Article  Google Scholar 

  • Beyer S, Macho C, Pinzger M, Penta MD (2018) Automatically classifying posts into question categories on Stack Overflow. In: 26th conference on program comprehension (ICPC), pp 211–221

  • Bogart C, Kästner C, Herbsleb J, Thung F (2016) How to break an API: cost negotiation and community values in three software ecosystems. In: 24th international symposium on the foundations of software engineering (FSE), pp 109–120

  • Borges H, Hora A, Valente MT (2016) Understanding the factors that impact the popularity of GitHub repositories. In: 32nd IEEE international conference on software maintenance and evolution (ICSME), pp 334–344

  • Boulanger JS, Robillard MP (2006) Managing concern interfaces. In: 22nd IEEE international conference on software maintenance (ICSME), pp 14–23

  • Brito A, Xavier L, Hora A, Valente MT (2018a) APIDiff: Detecting API breaking changes. In: 25th international conference on software analysis, evolution and reengineering (SANER), tool track, pp 507–511

  • Brito A, Xavier L, Hora A, Valente MT (2018b) Why and how Java developers break APIs. In: 25th international conference on software analysis, evolution and reengineering (SANER), pp 255–265

  • Businge J, Serebrenik A, van den Brand M (2012) Survival of Eclipse third-party plug-ins. In: 28th IEEE international conference on software maintenance (ICSM), pp 368–377

  • Businge J, Serebrenik A, van den Brand M (2013) Analyzing the eclipse API usage: Putting the developer in the loop. In: 17th european conference on software maintenance and reengineering (CSMR), pp 37–46

  • Businge J, Serebrenik A, van den Brand MGJ (2015) Eclipse API usage: the good and the bad. Softw Qual J 23(1):107–141

    Article  Google Scholar 

  • Chow K, Notkin D (1996) Semi-automatic update of applications in response to library changes. In: 12th international conference on software maintenance (ICSM), pp 359–368

  • Cliff N (2014) Ordinal methods for behavioral data analysis. Psychology Press

  • Cruzes DS, Dyba T (2011) Recommended steps for thematic synthesis in software engineering. In: 5th international symposium on empirical software engineering and measurement (ESEM), pp 275–284

  • Dagenais B, Robillard MP (2008) Recommending adaptive changes for framework evolution. In: 30th international conference on software engineering (ICSE), pp 481–490

  • Dig D, Johnson R (2005) How do APIs evolve? a story of refactoring. In: 22nd international conference on software maintenance (ICSM), pp 83–107

    Article  Google Scholar 

  • Dyer R, Nguyen HA, Rajan H, Nguyen TN (2013) Boa: a language and infrastructure for analyzing ultra-large-scale software repositories. In: 35th international conference on software engineering (ICSE), pp 422–431

  • Henkel J, Diwan A (2005) Catchup!: Capturing and replaying refactorings to support API evolution. In: 27th international conference on software engineering (ICSE), pp 274–283

  • Hora A, Robbes R, Valente MT, Anquetil N, Etien A, Ducasse S (2018) How do developers react to API evolution? a large-scale empirical study. Softw Qual J 26(1):161–191

    Article  Google Scholar 

  • Hora A, Valente MT, Robbes R, Anquetil N (2016) When should internal interfaces be promoted to public?. In: 24th international symposium on the foundations of software engineering (FSE), pp 280–291

  • Jezek K, Dietrich J, Brada P (2015) How Java APIs break - an empirical study. Inf Softw Technol 65(C):129–146

    Article  Google Scholar 

  • Kim M, Notkin D (2009) Discovering and representing systematic code changes. In: 31st international conference on software engineering (ICSE), pp 309–319

  • Konstantopoulos D, Marien J, Pinkerton M, Braude E (2009) Best principles in the design of shared software. In: 33rd international computer software and applications conference (COMPSAC), pp 287–292

  • Kula RG, Ouni A, German DM, Inoue K (2018) An empirical study on the impact of refactoring activities on evolving client-used APIs. Inf Softw Technol 93 (C):186–199

    Article  Google Scholar 

  • Mastrangelo L, Ponzanelli L, Mocci A, Lanza M, Hauswirth M, Nystrom N (2015) Use at your own risk: the Java unsafe API in the wild. In: 30th international conference on object-oriented programming, systems, languages, and applications (OOPSLA), pp 695–710

    Article  Google Scholar 

  • Mazinanian D, Ketkar A, Tsantalis N, Dig D (2017) Understanding the use of lambda expressions in Java. In: 32nd international conference on object-oriented programming, systems, languages, and applications (OOPSLA), pp 85:1–85:31

    Article  Google Scholar 

  • McDonnell T, Ray B, Kim M (2013) An empirical study of API stability and adoption in the Android ecosystem. In: 29Th international conference on software maintenance (ICSM), pp 70–79

  • Meng S, Wang X, Zhang L, Mei H (2012) A history-based matching approach to identification of framework evolution. In: 34th international conference on software engineering (ICSE), pp 353–363

  • Mezzetti G, Møller A, Torp MT (2018) Type regression testing to detect breaking changes in Node.js libraries. In: 32nd european conference on object-oriented programming (ECOOP), pp 7:1–7:24

  • Mitchell BS, Mancoridis S (2006) On the automatic modularization of software systems using the Bunch tool. IEEE Trans Softw Eng 32(3):193–208

    Article  Google Scholar 

  • Morrison P, Murphy-Hill E (2013) Is programming knowledge related to age? an exploration of Stack Overflow. In: 10th working conference on mining software repositories (MSR), pp 69–72

  • Moser S, Nierstrasz O (1996) The effect of object-oriented frameworks on developer productivity. Computer 29(9):45–51

    Article  Google Scholar 

  • Mostafa S, Rodriguez R, Wang X (2017) Experience paper: a study on behavioral backward incompatibilities of Java software libraries. In: 26th international symposium on software testing and analysis (ISSTA), pp 215–225

  • Murphy-Hill E, Zimmermann T, Bird C, Nagappan N (2013) The design of bug fixes. In: 35th international conference on software engineerin (ICSE), pp 332–341

  • Murphy-Hill E, Zimmermann T, Bird C, Nagappan N (2015) The design space of bug fixes and how developers navigate it. IEEE Trans Softw Eng 41(1):65–81

    Article  Google Scholar 

  • Nguyen HA, Nguyen TT Jr, GW, Nguyen AT, Kim M, Nguyen TN (2010) A graph-based approach to API usage adaptation. In: 25th international conference on object oriented programming systems languages and applications (OOPSLA), pp 302–321

  • Pinto G, Castor F, Liu YD (2014) Mining questions about software energy consumption. In: Working conference on mining software repositories (MSR), pp 22–31

  • Pinto G, Castor F, Liu YD (2014) Mining questions about software energy consumption. In: 11th working conference on mining software repositories (MSR), pp 22–31

  • Praditwong K, Harman M, Yao X (2011) Software module clustering as a multi-objective search problem. IEEE Trans Softw Eng 37(2):264–282

    Article  Google Scholar 

  • Prete K, Rachatasumrit N, Sudan N, Kim M (2010) Template-based reconstruction of complex refactorings. In: 26th international conference on software maintenance (ICSM), pp 1–10

  • Raemaekers S, van Deursen A, Visser J (2012) Measuring software library stability through historical version analysis. In: 28th international conference on software maintenance (ICSM), pp 378–387

  • Reddy M (2011) API Design for c++. Morgan Kaufmann Publishers, San Mateo

    Google Scholar 

  • Robbes R, Lungu M, Röthlisberger D (2012) How do developers react to API deprecation? the case of a Smalltalk ecosystem. In: 20Th international symposium on the foundations of software engineering (FSE), pp 56:1–56:11

  • Rogers EM (2003) Diffusion of innovations, 5th edn. Free Press, New York

    Google Scholar 

  • Sawant AA, Robbes R, Bacchelli A (2016) On the reaction to deprecation of 25,357 clients of 4 + 1 popular Java APIs. In: 32nd international conference on software maintenance and evolution (ICSME), pp 400–410

  • Sawant AA, Robbes R, Bacchelli A (2017) On the reaction to deprecation of clients of 4 + 1 popular Java APIs and the JDK. Empir Softw Eng 1–40

  • Schäfer T, Jonas J, Mezini M (2008) Mining framework usage changes from instantiation code. In: 30Th international conference on software engineering (ICSE), pp 471–480

  • Silva D, Tsantalis N, Valente MT (2016) Why we refactor? confessions of GitHub contributors. In: 24th international symposium on the foundations of software engineering (FSE), pp 858–870

  • Terra R, Valente MT, Czarnecki K, Bigonha RS (2015) A recommendation system for repairing violations detected by static architecture conformance checking. Software: Practice and Experience 45(3):315–342

    Google Scholar 

  • Wang W, Malik H, Godfrey M (2015) Recommending posts concerning API issues in developer Q&A sites. In: 12Th working conference on mining software repositories (MSR), pp 224–234

  • Wu W, Gueheneuc YG, Antoniol G, Kim M (2010) AURA: A hybrid approach to identify framework evolution. In: 32nd international conference on software engineering (ICSE), pp 325–334

  • Xavier L, Brito A, Hora A, Valente MT (2017a) Historical and impact analysis of API breaking changes: a large scale study. In: 24th international conference on software analysis, evolution and reengineering (SANER), pp 138–147

  • Xavier L, Hora A, Valente MT (2017b) Why do we break APIs? first answers from developers. In: 24th international conference on software analysis, evolution and reengineering (SANER), pp 392–396

  • Zhang T, Upadhyaya G, Reinhardt A, Rajan H, Kim M (2018) Are code examples on an online Q&A forum reliable? a study of API misuse on stack overflow. In: 40Th international conference on software engineering (ICSE), pp 886–896

Download references

Acknowledgements

We thank the 56 GitHub developers who participated in our study and shared their ideas and practices about breaking changes. This research is supported by grants from FAPEMIG, CNPq, and CAPES.

Author information

Authors and Affiliations

  1. Department of Computer Science (DCC), Federal University of Minas Gerais (UFMG), Pampulha, Belo Horizonte, 31270901, Brazil

    Aline Brito, Marco Tulio Valente, Laerte Xavier & Andre Hora

Authors
  1. Aline Brito
    View author publications

    You can also search for this author in PubMed Google Scholar

  2. Marco Tulio Valente
    View author publications

    You can also search for this author in PubMed Google Scholar

  3. Laerte Xavier
    View author publications

    You can also search for this author in PubMed Google Scholar

  4. Andre Hora
    View author publications

    You can also search for this author in PubMed Google Scholar

Corresponding author

Correspondence to Aline Brito.

Additional information

Communicated by: David Shepherd and Massimiliano Di Penta

Publisher’s note

Springer Nature remains neutral with regard to jurisdictional claims in published maps and institutional affiliations.

This article belongs to the Topical Collection: Software Analysis, Evolution and Reengineering (SANER)

Rights and permissions

Reprints and permissions

About this article

Check for updates. Verify currency and authenticity via CrossMark

Cite this article

Brito, A., Valente, M.T., Xavier, L. et al. You broke my code: understanding the motivations for breaking changes in APIs. Empir Software Eng 25, 1458–1492 (2020). https://doi.org/10.1007/s10664-019-09756-z

Download citation

  • Published:

  • Issue Date:

  • DOI: https://doi.org/10.1007/s10664-019-09756-z

Keywords

Search

Navigation