Why and How Java Developers Break APIs (SANER 2018)

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.

13beaa3b7239eca3319d54c6a9f3a85a?s=128

ASERG, DCC, UFMG

March 22, 2018
Tweet

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