Hello everyone! Being a Sylius Core Team member is fun – there is no doubt about that. Of course, we also need to make a lot of difficult decisions and actions regarding Sylius architecture, features, bug fixes, etc. The first of these is especially important, as it defines the foundation for all other technical decisions. Therefore, we decided that we need to be more transparent with the Sylius Community about our choices. Eventually, they affect Sylius users the most. To achieve this goal, we commenced a new approach to technical documentation – Architecture Decision Records.
Many Core Team members made architecture decisions in Sylius over the last few years. They were usually useful and well-received (three layers of Order-related entities, usage of the state machine concept, Resource and Grid). However, it can be hard for newcomers (or sometimes even for the existing Sylius developers) to comprehend the reasoning of these decisions. Of course, you can also ask us, and you’ll get the vast explanation… But we can do better, can’t we?
As you probably already know, we started a huge new feature recently – integration with ApiPlatform. New Sylius API is a big undertaking and it obliged us to rethink our approach to multiple development processes, from the testing to the implementation itself. We decided that, as with the roadmap and the whole code, we also want to be transparent with our architectural decisions. The inspiration was also architectural courses and conferences that some of us attended in the last months.
We’re also aware that documenting decisions allows easier iterations over the provided value. Hence, as we explain Sylius features with Behat scenarios, we’ve started documenting architectural decisions with Architecture Decision Records (ADRs).
We started simple, with the first ADRs prepared for the API for Product Options (consisting of some information about handling translations and options’ values). They were good, but we knew it’s just the beginning. To keep track of all architectural decisions we take, we have to iterate quickly over them and adapt them smoothly. We also had the feeling that what we need from the very beginning is some standard for this new kind of documentation. The standard that ideally would be both easy to read and sufficiently explainable.
We decided to use the MADR template, which provides comprehensive information about a taken decision, as well as is well prepared to be used with the Markdown notation. We also adjusted it a little bit, e.g. removing “Pros and Cons of the Options” section, or simplifying the introductory description. We also explained the conventions for our ADRs, to be transparent about our transparency.
You can check out all these changes in this Pull Request.
“What’s next?” you can ask. A pretty good question that definitely needs an answer. The most important thing which we want to focus on now is to carefully explain all the important architecture-related decisions with ADRs. Naturally, the new API will be the first one covered by them (as we concentrate on API development as well). However, we also plan to describe all essential architectural choices taken in the last few years.
Of course, there is a trap. We often see that when excited with a new tool, one is looking for the possibilities to use it EVERYWHERE.
It’s also something we’ve already seen with ourselves. So the challenge for the upcoming weeks (or months) would be not only introducing this amazing convention in Sylius but also not to overuse it. We’ll do our best :). Right now, you can find all the existing ADRs in this section of the Sylius/Sylius repository.
As always, we are looking forward to your feedback. Feel welcomed to contribute not only to the Sylius code but also to the documentation. Stay healthy and see you online!
