potiuk commented on PR #29940: URL: https://github.com/apache/airflow/pull/29940#issuecomment-1483424096
@julienledem @mobuchowski @bolkedebruin If I may suggest, I think what works REALLY well for future references are ADRs (Architecture Decision Records). I have tried it in the past without much of the success for "new" things. But I found it works REALLY well, when you have an existing solution and either rewrite it or bring it to a new context, especially if you know the reasoning and learning from the past. This is what we've done when we re-wrote breeze in Python, I used the opportunity to capture all the decisions in the form of ADRs and I think it is great - for me but also for anyone who asks a question "why are we doing this and that". I used the "rewrite" opportunity to capture all the big decisions there. As the result, every time someone asked (or contested) some of the decisions, I was - pretty much always - able to send the person to the right ADR rather than explain it over and over again. Some links to follow: * Nice intro to ADRS: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions * Our ADRs for breeze: https://github.com/apache/airflow/tree/main/dev/breeze/doc/adr * I used this tool for ADR management: https://github.com/npryce/adr-tools (not really needed, ADRs are meant to be maintained "by hand", it just makes it a little easier to do it consistently). -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
