Why and How Java Developers Break APIs (SANER 2018)

Slide 1

Slide 1 text

Why and How Java Developers Break APIs Aline Brito, Laerte Xavier, Andre Hora, Marco Tulio Valente SANER 2018

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

Library services are provided via APIs 5

Slide 6

Slide 6 text

In theory, APIs should be stable 6

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

Why do Developers Break APIs? 8

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

Dataset

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

Study Steps

Slide 21

Slide 21 text

Study Steps We mined daily commits 21

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

Study Steps We mined daily commits We used APIDiff to identify breaking changes We sent emails to developers asking the reasons behind changes 23

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

Definitions 25

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

Survey Results 28

Slide 29

Slide 29 text

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?

Slide 30

Slide 30 text

Q1: How often do changes impact clients? 30

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

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

Slide 33

Slide 33 text

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

Slide 34

Slide 34 text

Most common breaking changes 34

Slide 35

Slide 35 text

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

Slide 36

Slide 36 text

Most common breaking changes 36

Slide 37

Slide 37 text

Breaking changes per API element 37

Slide 38

Slide 38 text

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

Slide 39

Slide 39 text

Q2: Why do developers break APIs? 39

Slide 40

Slide 40 text

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

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

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

Slide 43

Slide 43 text

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

Slide 44

Slide 44 text

Q3: Why don’t developers deprecate broken APIs?

Slide 45

Slide 45 text

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

Slide 46

Slide 46 text

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.

Slide 47

Slide 47 text

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

Slide 48

Slide 48 text

Q4: What is the effort on clients to migrate?

Slide 49

Slide 49 text

What is the effort on clients to migrate? 49

Slide 50

Slide 50 text

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

Slide 51

Slide 51 text

Q5: How do developers document breaking changes? 51

Slide 52

Slide 52 text

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

Slide 53

Slide 53 text

How do developers document BCs? 53

Slide 54

Slide 54 text

How do developers document breaking changes? 54

Slide 55

Slide 55 text

How do developers document breaking changes? 55

Slide 56

Slide 56 text

Implications and Conclusions 56

Slide 57

Slide 57 text

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

Slide 58

Slide 58 text

*http://openjdk.java.net/projects/jigsaw 58 Implications to Language Designers This confirms the relevance of the new module system, being proposed to Java

Slide 59

Slide 59 text

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

Slide 60

Slide 60 text

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

Slide 61

Slide 61 text

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