Yes, I believe we should adopt ADRs in Operaton — but focus their use on major architectural decisions only. These are the kinds of changes that have a broad or lasting impact on the system, are difficult to reverse, or significantly affect how contributors interact with the codebase.
ADRs would help address two recurring challenges in open-source projects like Operaton. First, they improve transparency, making architectural reasoning visible and accessible beyond the core group of contributors. Second, they help preserve knowledge that often gets lost over time or buried in issues, code reviews, or chats.
They can also serve as a tool to improve communication and coordination. By providing a shared structure and a documented decision process, ADRs make it easier for contributors to propose changes, understand trade-offs, and participate in architectural discussions — especially in a distributed, asynchronous environment.
That said, there are challenges. One is ensuring that ADRs stay in sync with implementation. If code evolves but ADRs aren’t updated, they risk becoming misleading. Another is the housekeeping effort — as the project grows, we’ll need a way to identify outdated or superseded ADRs and manage them appropriately.
To keep the process lightweight, I would suggest starting with the MADR template, which is Markdown-based and easy to work with in Git. However, one important question we’ll need to address early on is where to store the ADRs. Options include a dedicated documentation repository, a wiki, or directly alongside the code — for example, in a /adr/ folder within the main repo. Personally, I lean toward storing them with the code to ensure they evolve together, but this should be discussed and agreed upon by the team.
Looking a bit further ahead, I’ve been considering whether we might eventually adopt a more comprehensive proposal format, inspired by Kafka’s KIP process. I’ve tentatively called this POEX (Proposal for Operaton Extension). A POEX would be used to design and justify significant features or system changes before implementation begins. It would cover motivation, technical design, compatibility considerations, and alternatives. Once a POEX is accepted, its conclusions could be formally recorded in an ADR — offering a clear and traceable path from idea to implementation.
That said, we should start small. Use ADRs for major topics only, keep the process lean at first, and revisit the idea of POEX and extended workflows if and when the need arises.
