APIDiff: Detecting API Breaking Changes (SANER 2018, Tools Track)

Libraries are commonly used to increase productivity. As most software systems, they evolve over time and changes are required. However, this process may involve breaking compatibility with previous versions, leading clients to fail. In this context, it is important that libraries creators and clients frequently assess API stability in order to better support their maintenance practices. In this paper, we introduce APIDIFF, a tool to identify API breaking and non-breaking changes between two versions of a Java library. The tool detects changes on three API elements: types, methods, and fields. We also report usage scenarios of APIDIFF with four real-world Java libraries.

Transcript

1. APIDiff: Detecting
   API Breaking Changes
   Aline Brito, Laerte Xavier, Andre Hora, Marco Tulio Valente
   SANER 2018, Tool Track
   

   View Slide

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

   View Slide

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

   View Slide

4. Library services are provided via APIs
   4
   

   View Slide

5. In theory, APIs should be stable
   5
   

   View Slide

6. But, 28% out of 500K API changes
   break backward compatibility
   Historical and Impact Analysis of API Breaking Changes: A Large-Scale Study
   SANER, 2017
   6
   

   View Slide

7. Which changes break my code?
   How stable is this library?
   7
   

   View Slide

8. 8
   On the owner side…
   Write migration documents
   Identify and revert accidental breaking changes
   

   View Slide

9. 9
   On the client side…
   Analyze the amount of breaking changes over time
   Select more stable libraries to depend on
   

   View Slide

10. APIDiff
    Detecting API Breaking Changes
    

    View Slide

11. 11
    APIDiff
    The tool analyses
    libraries available on git
    

    View Slide

12. Catalog of
    Breaking and Non-breaking Changes
    detected by APIDiff
    

    View Slide

13. Breaking Changes (BC)
    Changes performed in API elements that
    may break client applications
    13
    We exclude changes performed on
    deprecated API elements
    

    View Slide

14. 14
    Element Breaking Changes (BC)
    Type REMOVE TYPE, LOST VISIBILITY, CHANGE IN
    SUPERTYPE, ADD FINAL MODIFIER, REMOVE STATIC
    MODIFIER, RENAME TYPE, MOVE TYPE
    Method REMOVE METHOD, LOST VISIBILITY, CHANGE IN RETURN
    TYPE, CHANGE IN PARAMETER LIST, CHANGE IN
    EXCEPTION LIST, ADD FINAL MODIFIER, REMOVE STATIC
    MODIFIER, MOVE METHOD, RENAME METHOD, PUSH
    DOWN METHOD, INLINE METHOD
    Field REMOVE FIELD, LOST VISIBILITY, CHANGE IN FIELD
    TYPE, CHANGE IN FIELD DEFAULT VALUE, ADD FINAL
    MODIFIER, MOVE FIELD, PUSH DOWN FIELD
    

    View Slide

15. Example: Change in Access Modifiers
    15
    public int M1(String){
    ...
    }
    private int M1(String){
    ...
    }
    

    View Slide

16. Example: Change in Parameter List
    16
    public int M1(Context){
    ...
    }
    public int M1(){
    ...
    }
    

    View Slide

17. Example: Element Removal
    17
    public class C1{
    ...
    }
    public class C1{
    ...
    }
    

    View Slide

18. Example: Refactoring Operations
    18
    public int M1(String, Integer){
    ...
    }
    public int M2(String, Integer){
    ...
    }
    

    View Slide

19. Non-breaking Changes (NBC)
    Changes that do not break clients
    19
    

    View Slide

20. 20
    Element Non-Breaking Changes (NBC)
    Type ADD TYPE, GAIN VISIBILITY, REMOVE FINAL MODIFIER,
    ADD STATIC MODIFIER, ADD SUPERTYPE, EXTRACT
    SUPERTYPE, DEPRECATED TYPE
    Method ADD METHOD, PULL UP METHOD, GAIN VISIBILITY,
    REMOVE FINAL MODIFIER, ADD STATIC MODIFIER,
    DEPRECATED METHOD, EXTRACT METHOD
    Field ADD FIELD, PULL UP FIELD, GAIN VISIBILITY, REMOVE
    FINAL MODIFIER, DEPRECATED FIELD
    

    View Slide

21. Example: Change in Access Modifiers
    21
    private int M1(String){
    ...
    }
    public int M1(String){
    ...
    }
    

    View Slide

22. Example: Add Element
    22
    public class C1{
    public void M1(){
    …
    }
    }
    public class C1{
    }
    

    View Slide

23. Examples
    23
    

    View Slide

24. 24
    An image loading and
    caching library
    20K stars
    A framework to
    implement unit tests
    6K stars
    

    View Slide

25. Example 1: Detecting Changes in
    Version Histories
    25
    

    View Slide

26. 26
    Detecting Changes in Version Histories
    Useful to analyze several commits at once
    Useful to assess libraries stability
    

    View Slide

27. Detecting Changes in Version Histories
    27
    APIDiff diff = new APIDiff(
    “bumptech/glide”,
    “https://github.com/bumptech/glide.git”);
    Result result =
    diff.detectChangeAllHistory(“master”, Classifier.API);
    

    View Slide

28. Detecting Changes in Version Histories
    28
    APIDiff diff = new APIDiff(
    “bumptech/glide”,
    “https://github.com/bumptech/glide.git”);
    Result result =
    diff.detectChangeAllHistory(“master”, Classifier.API);
    

    View Slide

29. Example 2: Fetching New Commits
    29
    

    View Slide

30. 30
    Fetching New Commits
    Useful to monitor changes in a repository
    Contributors are notified shortly after BCs are introduced
    

    View Slide

31. Fetching New Commits
    31
    APIDiff diff = new APIDiff(
    “bumptech/glide”,
    “https://github.com/bumptech/glide.git”);
    Result result =
    diff.fetchAndDetectChange(Classifier.API);
    

    View Slide

32. Fetching New Commits
    32
    APIDiff diff = new APIDiff(
    “bumptech/glide”,
    “https://github.com/bumptech/glide.git”);
    Result result =
    diff.fetchAndDetectChange(Classifier.API);
    

    View Slide

33. Example 3: Detecting Changes in
    Specific Commits
    33
    

    View Slide

34. 34
    Detecting Changes in Specific Commits
    Useful to analyze pull requests
    Useful to detect accidental BCs
    

    View Slide

35. Detecting Changes in Specific Commits
    35
    APIDiff diff = new APIDiff(
    “mockito/mockito”,
    “https://github.com/mockito/mockito.git”);
    Result result =
    diff.detectChangeAtCommit(
    "4ad5fdc14ca4b979155d10dcea0182c82380aefa",
    Classifier.API);
    

    View Slide

36. Detecting Changes in Specific Commits
    36
    APIDiff diff = new APIDiff(
    “mockito/mockito”,
    “https://github.com/mockito/mockito.git”);
    Result result =
    diff.detectChangeAtCommit(
    "4ad5fdc14ca4b979155d10dcea0182c82380aefa",
    Classifier.API);
    

    View Slide

37. Detecting Changes in Specific Commits
    37
    APIDiff diff = new APIDiff(
    “mockito/mockito”,
    “https://github.com/mockito/mockito.git”);
    Result result =
    diff.detectChangeAtCommit(
    "4ad5fdc14ca4b979155d10dcea0182c82380aefa",
    Classifier.API);
    Category: Add Method
    Description: Method answersWithDelay(long, Answer)
    added in class org.mockito.AdditionalAnswers
    

    View Slide

38. Result Type
    38
    - category : String
    - description : String
    - path : String
    - element : String
    - javadoc : Boolean
    - deprecated : Boolean
    - breakingChange : Boolean
    - revCommit: RevCommit
    Change
    

    View Slide

39. Example 4: Filtering Packages
    39
    

    View Slide

40. 40
    Filtering Packages
    It is also possible to filter in/out packages
    Useful to detect changes in internal implementations
    

    View Slide

41. Filtering Packages
    41
    Result result =
    diff.detectChangeAtCommit(
    "4ad5fdc14ca4b979155d10dcea0182c82380aefa",
    Classifier.API);
    

    View Slide

42. Architecture
    

    View Slide

43. View Slide

44. 44
    Processing Module
    ● Git operations
    ● Instances library
    

    View Slide

45. 45
    Refactoring Module
    detects refactoring actions
    (reused from RefDiff)
    RefDiff: Detecting Refactorings in Version Histories
    Danilo Silva, Marco Tulio Valente - MSR, 2017
    

    View Slide

46. 46
    Analysis Module
    detects the changes in
    the library history
    

    View Slide

47. Future Work
    47
    

    View Slide

48. Future Work
    48
    ● Evaluate the precision of APIDiff
    ● Support to other programming languages
    ● Feature to analyze changes at release level
    

    View Slide

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

    View Slide

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

    View Slide