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
   

   View Slide

2. Motivation
   Libraries have a key importance in modern software development
   200K libraries
   2
   

   View Slide

3. Motivation
   Libraries have a key importance in modern software development
   200K libraries
   3
   

   View Slide

4. Motivation
   Libraries have a key importance in modern software development
   200K libraries
   4
   

   View Slide

5. Library services are provided via APIs
   5
   

   View Slide

6. In theory, APIs should be stable
   6
   

   View Slide

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
   

   View Slide

8. Why do
   Developers
   Break APIs?
   8
   

   View Slide

9. Outline
   1. APIDiff Tool
   2. Dataset
   3. Study Steps
   4. Definitions
   5. Results
   9
   

   View Slide

10. APIDiff
    A tool to detect API Changes
    APIDiff: Detecting API Breaking Changes SANER Tool Track, 2018
    https://github.com/aserg-ufmg/apidiff
    

    View Slide

11. APIDiff
    Breaking changes in types, methods, and fields
    ● Removal
    ● Change in access modifiers
    ● Change in parameter list
    11
    

    View Slide

12. APIDiff
    Breaking changes in types, methods, and fields
    ● Removal
    ● Change in access modifiers
    ● Change in parameter list
    12
    

    View Slide

13. APIDiff
    APIDiff warns if a breaking change is performed in internal or deprecated APIs
    io.reactivex.internal.util.ExceptionHelper
    13
    

    View Slide

14. APIDiff
    APIDiff warns if a breaking change is performed in internal or deprecated APIs
    io.reactivex.internal.util.ExceptionHelper
    14
    

    View Slide

15. Dataset
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

20. Study Steps
    

    View Slide

21. Study Steps
    We mined daily commits
    21
    

    View Slide

22. Study Steps
    We mined daily commits
    We used APIDiff to identify breaking changes
    22
    

    View Slide

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
    

    View Slide

24. 24
    Study Numbers
    116 days, May 8th to August 31th, 2017
    102 emails
    56 answers (55%)
    

    View Slide

25. Definitions
    25
    

    View Slide

26. Breaking Changes Candidates (BCC)
    Changes detected by APIDiff in public API elements
    26
    

    View Slide

27. Breaking Changes (BC)
    BCCs confirmed by the surveyed developers
    27
    

    View Slide

28. Survey Results
    28
    

    View Slide

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?
    

    View Slide

30. Q1: How often do changes impact clients?
    30
    

    View Slide

31. How often do changes impact clients?
    59 BCCs (39%) detected
    by APIDiff are BCs
    31
    

    View Slide

32. Unconfirmed Breaking Changes
    92 changes (61%)
    The surveyed developers did not agree
    they have an impact on clients
    32
    

    View Slide

33. Unconfirmed Breaking Changes
    Most unconfirmed BCCs are in internal
    or low-level APIs or in testing branches
    33
    

    View Slide

34. Most common breaking changes
    34
    

    View Slide

35. Most common breaking changes
    Most BCs are due to refactorings (47%)
    35
    

    View Slide

36. Most common breaking changes
    36
    

    View Slide

37. Breaking changes per API element
    37
    

    View Slide

38. Breaking changes per API element
    Most BCs are performed on
    methods (59%)
    38
    

    View Slide

39. Q2: Why do developers break APIs?
    39
    

    View Slide

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
    

    View Slide

41. New Feature (19 occurrences)
    “The changes in this commit were just a setup before
    implementing a new feature: chart data retrieval.”
    41
    

    View Slide

42. Simplify API (17 occurrences)
    “This method should not accept any parameters,
    because they are ignored by server.”
    42
    

    View Slide

43. Maintainability (14 occurrences)
    “Make support class lighter, by moving methods to
    Class and Method info.”
    43
    

    View Slide

44. Q3: Why don’t developers deprecate
    broken APIs?
    

    View Slide

45. Why don’t developers deprecate broken APIs?
    45
    (17 answers)
    

    View Slide

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.
    

    View Slide

47. Increase Maintainability Effort (8 answers)
    “In such a small library, deprecation will only add
    complexity and maintenance issues in the long run.”
    47
    

    View Slide

48. Q4: What is the effort on clients to migrate?
    

    View Slide

49. What is the effort on clients to migrate?
    49
    

    View Slide

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
    

    View Slide

51. Q5: How do developers document
    breaking changes?
    51
    

    View Slide

52. Do you plan to document the changes?
    14 developers 4 developers
    52
    

    View Slide

53. How do developers document BCs?
    53
    

    View Slide

54. How do developers document breaking changes?
    54
    

    View Slide

55. How do developers document breaking changes?
    55
    

    View Slide

56. Implications and Conclusions
    56
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

61. Thank you!
    Aline Brito, Laerte Xavier, Andre Hora, Marco Tulio Valente
    SANER 2018
    

    View Slide