I am in support of having adrs, and perhaps it's be helpful if there can be a brief description on what kind of changes would need an adr. Also if we can have a reminder on precommit which tells a committer to add an adr if a change fits some criteria (lines of code change or any other kind of metric?).
-- Regards, Aritra Basu On Mon, Dec 4, 2023, 11:56 AM Bartosz Jankiewicz <bjankiew...@google.com.invalid> wrote: > I've successfully adopted this technique in the past and it served well > for some use-cases. What I loved about ADR was its simplicity and > transparency. > > As you mentioned - it's not a "one solution fits all" kind of thing. I'd > love to have a summary for a given decision captured with ADR rather than > following a lengthy discussion in an issue or PR. At the same time more > complex designs should be captured with AIP as those frequently refer to > multiple decisions within given context. > > Bartosz > > On Mon, Dec 4, 2023 at 12:57 AM Jarek Potiuk <ja...@potiuk.com> wrote: > > > Hey everyone, > > > > I think we had a bit of clash in > > https://github.com/apache/airflow/pull/32319 where both "ideas" > > (serialization and common.sql) had not been sufficiently > > discussed/explained and I hope we can address it by adding (a bit) more > > "whys" to our (developer) documentation. > > > > I think a number of our past decisions and reasoning behind them are > often > > staying in the heads of the people who were discussing them, and even if > it > > is captured in past discussions, PRs, it's difficult to do "archeology" > on > > them and re-process them and understand what we wanted to achieve and > why. > > Some of those are big enough to have impact on future PRs etc. while not > > big enough to get to Airflow Improvement Proposals and I think we miss > > a bit of persistent "decision records" for them. > > > > Two cases in question: Serialization and Common.sql API - both of which > > have not been understood well by people involved in one, but not the > other > > in the past. > > > > With the "common.sql" PR (https://github.com/apache/airflow/pull/36015) > - > > my proposal is to add it in the form of ADR ("Architecture Decision > > Records' - which is a very simple and lightweight way of storing the > > decisions we made - and evolving them. > > > > ADRs are pretty popular and adopted in mature organisations/projects and > > I've used them in `breeze` > > https://github.com/apache/airflow/tree/main/dev/breeze/doc/adr and I > think > > they are perfect for capturing, context, decisions and putting down the > > consequences of some decisions. > > > > They are usually kept close to the code the decision is about, they are > > usually short and describe a single aspect of architectural decision, and > > they are aimed to be read whenever in the future, people who were not > > involved in those decisions can easily recover why the decisions are made > > and what are the consequences of it. > > > > I am not saying - of course - we should do it for all or even most > changes > > - I am talking about decisions that have potential impact on others - in > > the future. I.e. when we tell (this is how our approach should look in > the > > future for "general" behaviour. > > > > Both - serialization and common.sql are good examples of such decisions - > > that I believe deserve to be captured "why" we are doing them and what we > > wanted to achieve. > > > > WDYT? > > > > J. > > >
