ADR

[clement escoffier]

Hello,

ADR stands for Architectural Decision Records [1]. It's a way to keep track of some critical architecture decisions and follow the evolution. You can find various examples of them, such as on [2] and [3]

So, what's the relation with Quarkus? 

Over the past years, we made many decisions, and I challenge anyone to list all of them (except Guillaume, of course). Some decisions have been ad-hoc, more like a fact than an actual decision. We also changed recommendations over time (Json-B -> Jackson to mention one).

 
There are a few topics where it would be beneficial to keep track of them. To give some examples, let's mention two: the HTTP client used in core extensions and the JSON serialization.

An ADR is a short document that captures a decision. While an ADR is immutable (you can't change the past), it can be superseded as circumstances change and our choices too.
To give an example, I wrote one this morning [4]. At the moment, it's on the wiki, but it can be elsewhere. Some project uses a subdirectory in Git (and so get pull request to handle the discussion), some use a separate repository.

 
Some question you may have:

* What should be recorded?

We should record any crosscutting decision that impacts multiple extensions. We may not realize it at first; we can record it later. That's what happened for the HTTP client. Of course, not everything should be recorded. 

* Should it be documentation instead?

That a fundamental question, should it be in the documentation or an ADR? ADRs are not about documentation; it's an architectural decision in Quarkus. It has almost no interest for the end-user but can help us remember why we did things that way. 

* What's the scope? Quarkus Core, and probably some of the independent projects. It does not affect Quarkiverse extensions (even if extension authors can check the ADR) 

* Does it take time to record?

Not really, no more than 5 to 10 minutes. It can also be a good exercise to challenge the decision and be sure it's worthwhile and has benefits. There are multiple templates; I picked the simplest one [6].

* What are the benefits?

Remembering some of the decisions, the context, and why there were taken initially. It's perfectly normal to lost track of every decision, so ADRs keep track of them. 

* Can a decision be revised or revoked?

Yes, a new decision can be taken, and the old one can be superseded. Records are immutable, except for their status. But they can become deprecated or replaced.

* Any examples of ADR that could be useful?

Yes: The switch to Java 11, the non-application paths under "/q", micrometer as our recommended metrics support...

Thoughts?

Clement  

[1] - https://adr.github.io/
[2] - https://engineering.atspotify.com/2020/04/14/when-should-i-write-an-architecture-decision-record/
[3] - https://github.blog/2020-08-13-why-write-adrs/
[4] - https://github.com/quarkusio/quarkus/wiki/%5B001%5D--HTTP-Client-in-Quarkus-Core-Extensions
[5] - https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html

[Stephane Epardaud]

I like the idea, and we've struggled to find historical evidence for those decisions, spread between github issues, the mailing list and whatever meetings or private chats.

But I really dislike the idea of a discussion leading to an ADR being all around the place, and it being in a wiki doesn't help.

Probably if could belong on a special kind of github issue, or PR (if it ends up in git, like you proposed). And discussion could happen there, to be recorded too.

Naturally they'd be announced (before approuval) on the mailing list to point people to go there for discussion.

--
You received this message because you are subscribed to the Google Groups "Quarkus Development mailing list" group.
To unsubscribe from this group and stop receiving emails from it, send an email to quarkus-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CAKW6fiesWkhk0Oc1sZ9fF-%3Dx-t2KMJ4QeUwHd9B0NWd9qheFpg%40mail.gmail.com.

--

Stéphane Épardaud

[clement escoffier]

Le lun. 3 mai 2021 à 11:06, Stephane Epardaud <stephane...@gmail.com> a écrit :

I like the idea, and we've struggled to find historical evidence for those decisions, spread between github issues, the mailing list and whatever meetings or private chats.

But I really dislike the idea of a discussion leading to an ADR being all around the place, and it being in a wiki doesn't help.

Yes, I definitely agree. I did it in the wiki because I was (wrongly) supposing that link between pages would be supported (works in markdown - a nightmare with asciidoc). So, definitely not the way to go.

 

Probably if could belong on a special kind of github issue, or PR (if it ends up in git, like you proposed). And discussion could happen there, to be recorded too.

Storing the ADR on Git has a second advantage: you get them locally, which lets you consult them, and even be able to "find" things more easily from your IDE. 

Another advantage: no need for dates in the ADR itself, the git history is much more reliable than a field we will obviously forget to update. 

 

Naturally they'd be announced (before approuval) on the mailing list to point people to go there for discussion.

Yes, of course!

Clement 

[Loïc MATHIEU]

I used ADR in all my recent missions and I don't regret it ;)

ADR is a really good way to keep track of the decisions, including the "why" and the context (because some months ago, the why can be no more easily understandable).

So It's a big +1 for me, I usually use a very simple format ( Title, Context, Scenarii, Decision) with diagrams if possible, and  keep them in an ADR folder of the project's git repository. We didn't really discuss ADR on PR because we discuss them on meating but for an OSS project discussing them on PR or on mailing list based on scenarii from a PR seems a good way to do it.

Reading your ADR, there is only the decision not the scenarii, I often find it interesting to track what has been investigated and discarded, it can often answer the question "but why don't we do this way instead" a few months later ...

Regards,

Loïc

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CAKW6fifJMiVz1JBHDC4YvCD7n0CQ3cXyCnmwfHyCO5sAaCy3-Q%40mail.gmail.com.

[clement escoffier]

Le lun. 3 mai 2021 à 11:58, Loïc MATHIEU <loik...@gmail.com> a écrit :

I used ADR in all my recent missions and I don't regret it ;)

ADR is a really good way to keep track of the decisions, including the "why" and the context (because some months ago, the why can be no more easily understandable).

So It's a big +1 for me, I usually use a very simple format ( Title, Context, Scenarii, Decision) with diagrams if possible, and  keep them in an ADR folder of the project's git repository. We didn't really discuss ADR on PR because we discuss them on meating but for an OSS project discussing them on PR or on mailing list based on scenarii from a PR seems a good way to do it.

Reading your ADR, there is only the decision not the scenarii, I often find it interesting to track what has been investigated and discarded, it can often answer the question "but why don't we do this way instead" a few months later ...

This is because the template I used didn't capture the scenarii. We can add that.

Which template did you use?

Clement 

[Ken Finnigan]

I think we'd still need a date in an ADR for the situation where we're adding a record for a decision that is some time after it became active?

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CAKW6fifJMiVz1JBHDC4YvCD7n0CQ3cXyCnmwfHyCO5sAaCy3-Q%40mail.gmail.com.

[Loïc MATHIEU]

@clement escoffier I guess I uses my own template that is more or less the one you use plus a scenarii section

@Ken Finnigan we usually use a single date that is the date of the decision, if the ADR is written before and a draft => the date will be updated when the ADR is finished, if written after the decision, the date of writing is of no importance for me. If ADR are in git, you can still find it's historical update dates in git history.

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CAKeeVe4qdE72VMJz%2Bq-ROiZAn59z5K4o-pDw6vOeGM%2BASqpiiw%40mail.gmail.com.

[Ken Finnigan]

I need to be clearer, I mean we need a date on the ADR for when it's effective if written much later. With git, we'd have a date in the history of when the ADR was created, but not when it became effective

[Loïc MATHIEU]

There is a date in the status section Clement's ADR.

[Ken Finnigan]

Yes, but Clement had mentioned removing the need for a date if we moved to git.

I wanted to point out we still need a date even if we move to git

[Max Rydahl Andersen]

+1 on doing this and I would just add it to our GitHub quarkusio repo as a top level /adr folder.

PRs used to discuss it - we can even hookup hackmd.io to it for more collaborative discussions/edits.

one thing I noted was " It does not affect Quarkiverse extensions" ...I just want to clarify that quite a good amount
of the core platform work affects such extensions as that affects how the ecosystem is wired together.

But even the more reasons to get these things recorded in ADR's.

/max

--

You received this message because you are subscribed to the Google Groups "Quarkus Development mailing list" group.
To unsubscribe from this group and stop receiving emails from it, send an email to quarkus-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CAKW6fiesWkhk0Oc1sZ9fF-%3Dx-t2KMJ4QeUwHd9B0NWd9qheFpg%40mail.gmail.com.

/max
https://xam.dk/about

[George Gastaldi]

+1, there is even a Command line tool that facilitates the creation of ADR docs: https://github.com/adoble/adr-j

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CB395F5B-5A01-464C-8008-A0E8E7E247E6%40redhat.com.

[clement escoffier]

Hello,

Thanks for the feedback.

I created https://github.com/quarkusio/quarkus/pull/16996 which setup the ADR structure in the git repository (much better than the wiki)

I also updated the template to contain a date and use cases. The template is derived from MADR. 

Let me know what you think,

Clement