potiuk commented on a change in pull request #19867:
URL: https://github.com/apache/airflow/pull/19867#discussion_r758681427
##########
File path: dev/breeze/doc/adr/0001-record-architecture-decisions.md
##########
@@ -0,0 +1,48 @@
+<!--
Review comment:
Let's see.
I saw a few failures, and a few successes.
I've also head a few complaints that Breeze's/CI design decisions were not
documented (in fact they are all documented and explained in those documents:
* BREEZE.rst
* CI.rst
* IMAGES.rst
* PULL_REQUEST_WORKFLOW.rst
* LOCAL_VIRTUALENV.rst
and possibly few other places.
I think there is clearly a need to understand why certain choices were made
and at least in semi-structured way that will be easy to track. This is an
attempt to not mix design decisions, with resulting user documentation (which
was actually the main problem with the previous approach).
So I think a good way to capture desing decisions and keep them close to the
code is good. This is because if we keep them in Google Docs, they will be
easily lost. They also have one problem which ADRs handle - you can easily
create an ADR where the decision is changed or updated, and adr tool has a nice
way to create new ADR wchih supersedes the previous one (with automated
references in both docs). This is kinda pain to maintain if you have "live"
documentation in docs, because either you keep on manually adding new docs and
try to refer between them somehow (which one is the last one? is this the most
recent decision?) or they contain only the latest decision with lack of easy
visble evolution of the decision. Or - more lkely - they are never updated and
contain only the old decisions.
I think Google Docs are one of the ways (similarly as comments in PRs/issues
and slack discussions) to actually "do" the discussion, but I find ADRs as
particularly good to permanently "capture" the decisions for future self and
people who will be trying to find out some WHYs in the future.
--
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]
