BC ("Be careful") when dealing with BC ("Backwards compatibility")!

Maintaining compatibility promises is part of keeping healthy relationship with community and customers.
As maintainers of a framework that builds upon Symfony, being in turn used by other developers, we have a taste of both worlds.

We will explore different approaches, starting with semantic versioning and going through different libraries. We will go behind the reasons why certain choices are made, and what consequences they have to both developers and maintainers. We will also emphasize how those dilemmas affect our everyday planning and development. Finally, we will take a look at a particular case of performing major changes across entire codebase, by looking at a specific case that happened to our own product – a rebranding while maintaining compatibility. We will dive into specific solutions we came up with, and what challenges needed to be overcome – some of which proved to be a surprise.

“How to enforce class residing under two namespaces?”, “does class_alias work as one would expect?”, “how would autoloading work in this scenario?” are, among others, questions we needed to answer and that would like to share answers to.

Transcript

1. BC ("Be careful") when dealing with BC ("Backwards compatibility")! Konrad Oboza Brussels 8.12.2023
2. About me • Konrad Oboza, Software Engineer at Ibexa for 6 years • focusing on Ibexa DXP - Symfony based Digital Experience Platform • PHP7/8, Symfony, MySQL, Doctrine, Varnish, Redis • https://github.com/konradoboza • konrad.oboza@ibexa.co • https://www.linkedin.com/in/konrad-oboza
3. Who is Ibexa? 24 years of Digital Experience expertise 100 Collaborators +50000 Members +250K Installations +200 Partners +5M Downloads 160 Countries with users Open Source Commercial Lyon Paris Cologne Katowice Kraków Oslo Porsgrunn Madrid London
4. What actually is Ibexa DXP? • Symfony-based framework • multi-repository (60+) • tiers: • Ibexa/oss - publicly available via Packagist, • Ibexa/headless - private, Satis • Ibexa/experience - private, Satis • Ibexa/commerce - private, Satis • tons of APIs and extension points • Twig helpers, configurations
5. Q: Any major codebase refactor?
6. Q: Is this code directly used to build upon?
7. What does keeping BC promise really mean? • releasing our products in the spirit of SemVer (major.minor.patch) • ensuring smooth upgrades of customers’ projects • providing proper extension points for customizing our code • making sure only the provided ones are used 🙂
8. • Divided into: • Backend • Consumption • Extensibility (custom implementation) • Frontend • Exceptions: • Security • 3rd party code • @internal and @experimental • internal data formats Backwards compatibility promise
9. Examples of keeping the BC promise
10. 1. Renaming the method
11. 2. Updating SQL schema by adding a new column
12. 2. Upgrade script (same goes for PostgreSQL)
13. 3. SQL update + keeping data in-tact with the previous schema version
14. 4. Fixing typo can also be a BC break…
15. “Special cases” of undergoing BC promise
16. Storefront • commerce shop front • detachable component • multiple extension points What is it about? Caveats: • Twig variable names • object types served by the backend • YAML configuration
17. HTTP cache tagging • advanced caching capabilities • content-aware • enabled in the PHP API by default • allow manual tagging (via controllers or Twig templates) What is it about? Caveats: • maintaining HTTP cache tags patterns
18. Ibexa Design System • templating system • allows defining user themes What is it about? Caveats: • any template path starting with: @ibexadesign/ should be preserved
19. Company rebranding
20. eZ Systems is now Ibexa!
21. How hard can it be…? • not an easy preg_replace ;) • code references • prefixes • namespaces • new GitHub organization, new repositories • compatibility layer
22. New GitHub flow • github.com/ezsystems vs github.com/ibexa • repositories counterparts • introduced “merge-up” flow • keeping old repositories history
23. Rebranding commands • processing different kinds of code • what about database-stored configuration? • for PHP rebranding: https://github.com/nikic/PHP-Parser • we produce a new code complying with the new company name…
24. What about the existing code?
25. ibexa/compatibility-layer • all the tools needed to rename the code gathered in one place • making references to the legacy namespaces working without any changes • keeping track of and adjusting the new code arriving along the way • restructuring repositories and establishing name conventions • introducing src/contracts • covering with tests ran to check if old and new classes are compatible
26. Solution Pros Cons class_exists + filetree duplication • less effort • each class needs to be copied and contain this call referring to the new namespace, • using the old classname might fail if it’s done first and there is lack of at least one class duplicate Composer optimized autoloader • less effort, • autoloader works reliably, • class maps are generated for us • custom class maps cannot be imported, • customers need to enable it in their projects Class map + custom autoloading • no duplicated filetree – less code to maintain, • classes sharing most of their namespace don’t need to be put inside class map • increase in PHP memory usage – big class map Classes residing under two namespaces?
27. Custom autoloading
28. class_alias
29. class-map.php (…)
30. Semantic configuration • main key needs to be: ibexa • custom implementation of: Symfony\Component\DependencyInjection\ ContainerBuilder • custom CompilerPasses • custom mappings related to: • service definitions • bundles configuration keys • service tags • container parameters
31. Aftermath
32. Some parts still follow the old naming convention… • database-related naming – extensive schema, tons of upgrade script needed, • “FieldTypes” - building blocks, potentially millions of records affected! • HTTP-cache – 3rd party custom tagging/VCL subroutines -> production performance
33. Ibexa DXP plugin for PHPStorm
34. Conclusion
36. Ibexa is a part of QNTM ecosystem
37. Thank you!