This document discusses backward compatible development and provides examples. It explains that backward compatible approaches introduce new implementations alongside existing ones without removing existing code. This is achieved by proxying calls to the new implementations. Backward incompatible approaches remove existing implementations and refactor code to use new ones exclusively. The document also discusses specific cases like adding new methods, properties or constants, and identifies some subtler backward incompatible changes like adding functionality without reusing interfaces. It provides resources for backward compatible development best practices and change discussions.

1. Backward Compatible Development In Examples
Sergii Ivashchenko | Magento Community Engineering

2. © 2019 Adobe. All Rights Reserved. Adobe Confidential. 2

3. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
Radio: Mono -> Stereo
3

4. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
Mono radio station implementation
4

5. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
Extended implementation reuse original
5

6. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
Add new extended/improved implementation?
6
Backward Incompatible Approach Backward Compatible Approach
Introduce new implementation to
compete with existing Proxy old method calls to new
introduced interfaces/classes

7. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
Money: Cache -> Check -> Card -> Contactless
7

8. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
Deprecation
8

9. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
Replace existing implementation with newer and better
9
Backward Incompatible Approach Backward Compatible Approach
Remove existing implementation and
refactor code to use new one
Introduce new implementation and mark
old as deprecated
(there’s a small nuance - see few slides later)

10. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
MacBook: USB -> USB-C
10

11. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
Adapter
11

12. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
Introducing new interface, adapting old
12

13. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
Get rid of old ugly implementation
13
Backward Incompatible Approach Backward Compatible Approach
Remove existing implementation and
refactor code to use new one
Proxy old method calls to new
introduced interfaces/classes
(use deprecated tag)

14. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
Is adding new staff backward compatible?
14

15. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
Adding a new non-private method
15

16. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
Even more likely…
16

17. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
Adding a new non-private property
17

18. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
Even more likely…
18

19. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
Adding a new non-private constant
19

20. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
Even more likely…
20

21. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
A couple of backward incompatible changes
that is not so easy to identify:
21

22. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
Adding a functionality replacement without reusing existing interfaces
22

23. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
Declaring a constructor with optional parameters
23

24. © 2019 Adobe. All Rights Reserved. Adobe Confidential.
There should be no obstacles for making things better
▪ Backward compatible development guide:
▪ https://devdocs.magento.com/guides/v2.3/contributor-guide/backward-compatible-
development/
▪ Be aware of introduced backward incompatible changes:
▪ https://devdocs.magento.com/guides/v2.3/release-notes/backward-incompatible-
changes/
▪ Discuss if not sure:
▪ Slack channel: #appdesign
▪ Public Architecture Discussion meeting every Wednesday, 18:30 Lviv time
▪ https://github.com/magento/architecture/wiki
24

25. @sergeivaschneko
Lviv 2019