Why and How Java Developers Break APIs (SANER 2018)

Modern software development depends on APIs to reuse code and increase productivity. As most software systems, these 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 report the results of an almost 4-month long field study with the developers of 400 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. After identifying breaking changes, we asked the developers to explain the reasons behind their decision to change the APIs. During the study, we identified 59 breaking changes, confirmed by the developers of 19 projects. 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. We conclude by providing suggestions to language designers, tool builders, software engineering researchers and API developers.

Transcript

1. Why and How Java Developers Break APIs Aline Brito, Laerte Xavier, Andre Hora, Marco Tulio Valente SANER 2018
2. Motivation Libraries have a key importance in modern software development 200K libraries 2
3. Motivation Libraries have a key importance in modern software development 200K libraries 3
4. Motivation Libraries have a key importance in modern software development 200K libraries 4
5. Library services are provided via APIs 5
6. In theory, APIs should be stable 6
7. But, 28% out of 500K API changes break backward compatibility Historical and Impact Analysis of API Breaking Changes: A Large-Scale Study SANER 2017 7
8. Why do Developers Break APIs? 8
9. Outline 1. APIDiff Tool 2. Dataset 3. Study Steps 4. Definitions 5. Results 9
10. APIDiff A tool to detect API Changes APIDiff: Detecting API Breaking Changes SANER Tool Track, 2018 https://github.com/aserg-ufmg/apidiff
11. APIDiff Breaking changes in types, methods, and fields • Removal • Change in access modifiers • Change in parameter list 11
12. APIDiff Breaking changes in types, methods, and fields • Removal • Change in access modifiers • Change in parameter list 12
13. APIDiff APIDiff warns if a breaking change is performed in internal or deprecated APIs io.reactivex.internal.util.ExceptionHelper 13
14. APIDiff APIDiff warns if a breaking change is performed in internal or deprecated APIs io.reactivex.internal.util.ExceptionHelper 14
15. Dataset
16. 16 Top 2,000 projects by stars We discard projects without the keywords Library(ies), API(s), framework(s), and deprecated projects (449 projects) We inspect the projects documentation 400 libraries and frameworks
17. Top 2,000 projects by stars We discard projects without the keywords Library(ies), API(s), framework(s), and deprecated projects (449 projects) We inspect the projects documentation 17 400 libraries and frameworks
18. 18 Top 2,000 projects by stars We discard projects without the keywords Library(ies), API(s), framework(s), and deprecated projects (449 projects) We inspect the projects documentation 400 libraries and frameworks
19. 19 Top 2,000 projects by stars We discard projects without the keywords Library(ies), API(s), framework(s), and deprecated projects (449 projects) We inspect the projects documentation 400 libraries and frameworks
20. Study Steps
21. Study Steps We mined daily commits 21
22. Study Steps We mined daily commits We used APIDiff to identify breaking changes 22
23. Study Steps We mined daily commits We used APIDiff to identify breaking changes We sent emails to developers asking the reasons behind changes 23
24. 24 Study Numbers 116 days, May 8th to August 31th, 2017 102 emails 56 answers (55%)
25. Definitions 25
26. Breaking Changes Candidates (BCC) Changes detected by APIDiff in public API elements 26
27. Breaking Changes (BC) BCCs confirmed by the surveyed developers 27
28. Survey Results 28
29. 29 Survey Questions 1. Why did you perform these changes? 2. Do you agree these changes can break clients? If yes, could you quantify the amount of work to use the new implementation? 3. Why didn’t you deprecate the old implementation? 4. Do you plan to document the changes? If yes, how?
30. Q1: How often do changes impact clients? 30
31. How often do changes impact clients? 59 BCCs (39%) detected by APIDiff are BCs 31
32. Unconfirmed Breaking Changes 92 changes (61%) The surveyed developers did not agree they have an impact on clients 32
33. Unconfirmed Breaking Changes Most unconfirmed BCCs are in internal or low-level APIs or in testing branches 33
34. Most common breaking changes 34
35. Most common breaking changes Most BCs are due to refactorings (47%) 35
36. Most common breaking changes 36
37. Breaking changes per API element 37
38. Breaking changes per API element Most BCs are performed on methods (59%) 38
39. Q2: Why do developers break APIs? 39
40. Why do developers break APIs? 40 Motivation Description Occur. NEW FEATURE BCs to implement new features 19 API SIMPLIFICATION BCs to simplify and reduce the API complexity and number of elements 17 MAINTAINABILITY BCs to improve the maintainability and the structure of the code 14 BUG FIXING BCs to fix bugs in the code 3
41. New Feature (19 occurrences) “The changes in this commit were just a setup before implementing a new feature: chart data retrieval.” 41
42. Simplify API (17 occurrences) “This method should not accept any parameters, because they are ignored by server.” 42
43. Maintainability (14 occurrences) “Make support class lighter, by moving methods to Class and Method info.” 43
44. Q3: Why don’t developers deprecate broken APIs?
45. Why don’t developers deprecate broken APIs? 45 (17 answers)
46. Why don’t developers deprecate broken APIs? 46 Developers do not deprecate elements affected by BCs mostly due to the extra effort to maintain them.
47. Increase Maintainability Effort (8 answers) “In such a small library, deprecation will only add complexity and maintenance issues in the long run.” 47
48. Q4: What is the effort on clients to migrate?
49. What is the effort on clients to migrate? 49
50. What is the effort on clients to migrate? According to the surveyed developers, the effort to migrate to the new API versions is small. 50
51. Q5: How do developers document breaking changes? 51
52. Do you plan to document the changes? 14 developers 4 developers 52
53. How do developers document BCs? 53
54. How do developers document breaking changes? 54
55. How do developers document breaking changes? 55
56. Implications and Conclusions 56
57. Most unconfirmed BCCs affect internal or low-level APIs. 57 Implications to Language Designers However, internal APIs can be used by external clients, since they are public
58. *http://openjdk.java.net/projects/jigsaw 58 Implications to Language Designers This confirms the relevance of the new module system, being proposed to Java
59. 59 Implications to Practitioners Many unconfirmed BCCs do not have internal or experimental in their names. Practitioners should use internal in low-level or internal API names
60. Why do Java developers break APIs? • New features • API simplification • Improve maintainability How do Java developers break APIs? • Move Method • Remove Class • Change in Parameter List • Rename Method • Move Class 60
61. Thank you! Aline Brito, Laerte Xavier, Andre Hora, Marco Tulio Valente SANER 2018