Adopt ADR process for deciding architectural approaches

[garypen]

As a project evolves, it's often a good idea to have a written record of decisions and a mechanism for promoting discussion about those decisions. I've had good experiences in the past with an ADR based approach to this.

I'm proposing that we adopt ADRs into our decision making process and I've created a draft ADR so that we can try out the process and see what we like/don't like about it.

[cecton]

It looks like Rust's RFCs 😅 I fear we will have much discussion and little coding. For example in this draft ADR about telemetry I feel like this should have been a slack message to the entire team that says "hey folks please use #[instrument(skip_all, ...)] by default when you want to instrument things otherwise it kills the perf"

[Geal]

it could be a slack message, but then future hires or contributors won't find it easily. Like RFCs, it gives context on a decision (even minor ones) that we can easily find in the future

[garypen]

I do think there's a balancing act to these things. We need to use our judgement and sometimes use slack and sometimes use ADRs. In this case, I do think there's more substance than a series of slack messages could convey, especially when considering future contributors who can't access slack.

[o0Ignition0o]

I really dig ADRs not only because it allows us to record our decisions, but also the context/ tradeoffs made, and when to revisit the decisions.

It helps us scale the team, and maintain the codebase over time.

+1 for me

[Geal]

I'm all for using ADRs, and that reminds me I wanted to write one to explain the HTTP restart process 😄

[Geal]

I'd like ADRs like this one to reference actual code or bugs we encountered, to provide more context if someone wants to explore the original problem, to understand it or find another solution

[o0Ignition0o]

+1, it's a super efficient way to explain what, but especially why

[garypen]

Agreed. I'll flesh out the draft ADR I created when I have a few comments against it.

[garypen]

I think the majority opinion is that we should give ADRs a try. Here's my refined proposal:

• adopt a lightweight adr process which results in content in adr directory.
• review after 3 months and decide whether to continue/dis-continue

I'll lock this discussion for now and we'll re-open it in 3 months to record our verdict.