Use Architecture Decision Records (ADR) for Cristal?

Cristal
#1

Hi devs,

I’d like to propose that we try to record our architecture decisions using an ADR for Cristal.

The rationale is that after some it’s hard to remember why we took some decision and while we can try to search for it in the past mailing lists/forum posts/matrix or IRC chats, it’s not easy. So the idea would be to:

  • For any architecture decision we propose it on the forum (our current practice)
  • When agreed, we add one or several ADRs (an ADR is supposed to contain only 1 item).

Example:

  • Decision to code Cristal using type script

For more info about ADRs, see:

Furthermore, I’m proposing that we use xwiki.org to hold the Cristal ADRs, using a custom XClass/XSheet/LD (we could make it an app on contrib), with the following xproperties:

  • Title: this is the doc title, not an xproperty
  • Decision: the decision taken
  • Context: Explains the context in which the decision was taken
  • Pros/Cons: List of alternatives with pros and cons
  • Decision date
  • Links: links to related URLs, including the forum link where the decision was taken
  • Consequences: what are the consequences of that decision. This is to be amended across time, the rest should not be touched anymore once the decision has been taken.

WDYT?

Thanks

PS1: We could test that for Cristal and it works well, we could also propose it for XS dev.
PS2: It feels a bit like design.xwiki.org but it’s not the same scope and size (design.xwiki.org is more geared towards implementation and ADR are smaller and focused more on architecture decisions). Design.xwiki.org entries could link to ADR decisions though, where needed.

2 Likes
#2

+1 thanks

#3

First implementation done, see https://cristal.xwiki.org/xwiki/bin/view/ADR/Coding%20is%20done%20in%20Typescript/ and https://cristal.xwiki.org/xwiki/bin/view/ADR/

Implemented in Loading...

#4

I’ve been wondering more about this because we need to answer the following questions:

  1. When do we create an ADR? Do we do it for all decisions (cumbersome) or only for large decisions?
  2. Do we link from ADR to design.xwiki.org or from design.xwiki.org to ADR? Which one is the source of truth?

For 1), I think that one easy rule is that any forum thread tagged with proposal should lead to an ADR.

For 2), I’ve started to review if there’s really a difference between ADR and design.xwiki.org. Let’s look at the XClass for design.xwiki.or (i.e. ProposalCode.ProposalClass):

  • Product: needed in the ADR too if we want to use it for different products (and we have it already)
  • Name: same as ADR’s title
  • Type (Design, Requirements, Feature, Implementation, etc): not in our current ADR impl but could be. Not sure we really need this field and not sure we’ve ever really used it.
  • Status: there’s a difference here. An ADR is something that was agreed on while design.xwiki.org currently contains work in progress, or stuff that were dropped. However, it’s not a problem to have this concept for an ADR and only focus on the “Completed” ones.
  • Participants: would be ok for an ADR. Not sure we need it, anyone replying on the forum is actually a participant, yet we often don’t update the participants field. I think I’d change that field to be “Proposers” instead (ie the list of people who are proposing it).
  • Issues/Mails/Other URLs: this could all be merged in a single Links field (which we have in our current ADR impl)
  • Description: We don’t really have it in our ADR. We have a Decision and a Alternatives with pros/cons. The way I see it, we could rename Description into Proposal, and it would list the alternatives with pros/cons, and have another Decision xproperty which would be used to explicitly list the decided/agreed decision (something we’re lacking on design.xwiki.org ATM as we never know if the entries have been updated after the discussion on the forum or not).
  • Then we could add a Consequences field, which we have in our ADR for registering future consequences of the decision taken.
  • We should also add a decision date as we have in the ADR impl.
  • Last, we could add a Context field to define what the proposal is about and the context of the proposal (why is it proposed).

So, all in all, I think an design.xwiki.org is an ADR and we just need to massage it a bit.

What we could imagine:

The general process would be:

  • Make a proposal on the forum (with the full proposal in the forum post or by pre-creating an entry on adr.xwiki.org and linking to it)
  • Once the proposal is agreed on the forum, create or update adr.xwiki.org to record the decision and the decision date (and make sure the Proposal xproperty is also up to date), set the status to Closed/Completed/Agreed.
  • Close the forum post as solved, with a link to adr.xwiki.org

WDYT? Should I send a proposal on the https://forum.xwiki.org/c/dev/13 category to propose this for all and not just for Cristal?

Refactor design.xwiki.org into adr.xwiki.org + best practice to use it
#5

From my understanding, ADRs and design pages focus on two different aspects:

  • ADRs aims at explaining the why behind architectural decisions
  • design pages aims at documenting the how (e.g., implementation details, diagrams, etc.)

Therefore, it feels like the best option for me, it to keep both separate, and to possibly use ADRs as justification for design choices.

But, if we consider that what we are currently doing is close to ADRs, then +1 to migrate design to ADR.

#6

Thanks for the feedback.

Could you be more specific and tell me what fields listed above wouldn’t work for our current design pages? I don’t see any on my side.

For me, the whole goal of this discussion is to see if we could use the same tool for everything. We can name the tool the way we want (ADR or something else), it doesn’t matter much.

In the proposal above, I mentioned:

Type (Design, Requirements, Feature, Implementation, etc):

This was to account for the potentially different usages of the tool.

Since the concept of ADR already exists, I’d be in favor of using its name rather than inventing a new one. It feels good to reuse that name since people seeing adr.xwiki.org will understand what it’s about more easily than design.xwiki.org (BTW talking about design for implementation is not better than talking about the architecture of the implementation, for me design and architecture can be considered synonyms in our context).

An alternative is to name it an IDR (Important Decision Records), IPR (Important Proposal Records), or something like this, but I’d prefer to not reinvent the wheel and call it an ADR. Especially since I believe everything we currently have on design.xwiki.org is about architecture/design. It contains architecture decisions, whether they’re about requirements, about the UI, about a feature to add or remove, about some important implementation details (Deciding to use such framework or such implementation pattern, for ex, is an architecture decision).

WDYT? Was I able to convince you? :slight_smile:

PS: BTW I like what is at ADR process - AWS Prescriptive Guidance I think we could re-use a lot from it.

PPS: that doc says:

When the team accepts an ADR, it becomes immutable. If new insights require a different decision, the team proposes a new ADR. When the team accepts the new ADR, it supersedes the previous ADR.

I think we need a field for that, at least a “state” for it: “Superseded”.

#7

+1

Also, after more discussions, we concluded that:

  • it’s ok to merge the concepts of design page and ADR (under the adr.xwiki.org domain) and migrate existing design pages
  • forum proposals impacting the design should lead to an ADR
  • documentation pages should point to ADRs for traceability (e.g., to justify a coding style rule)
#8

I think we said the opposite actually:

  • ADR pages should link to reference documentation
  • Reference documentation should NOT link to ADR pages since reference doc are not about the dev process.
#9

To be more precise we agreed that it should include proposals about the product or development processes. It doesn’t include other proposals (e.g. roadmap proposals, or Clean up of xwiki.org recycle bins)

#10

General proposal for all product sent at Refactor design.xwiki.org into adr.xwiki.org + best practice to use it