We should adopt Architecture Decision Records

[Relequestual]

Current problem

With JSON Schema, we have often been asked why something is the way it is. Sometimes we can answer easily, sometimes we have to ask a specific person, sometimes we have to play the "We inherited the project and it was just like that" card. This is not an ideal situation.

Proposed solution

Architecture Decision Records (ADR) is a well established approach to documenting important "architectural" decisions.

 ADRs have a status, so we can also use them to track proposals as well as having records for rejected, deprecated, or superseded decisions that impact the project.

While this might seem a little heavy, it can be really light and clear, and I believe the benefits will outweigh the small cost in using it. Additionally, rationalising decisions on paper may be a useful exercise to clarify understanding proposals and key decisions.

Tell me more


Canonically referenced blog post: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions

Website: https://adr.github.io

Markdown format: https://adr.github.io/madr

What would we have to actually do?

When key decisions are identified or proposed, a new ADR should be created.
This involves duplicating a template and filling in as many details as appropriate.

We would need to initialise each repo where we want to use ADRs (Most I think).

There is a markdown template and most of the sections are optional. We can tweak it as we need.

While the MADR page outlines an approach using a fork of a tool, the fork is now archived and the owner of the tool said they do not wish to support MADR format.

As such, I would propose we use Log4brains (https://github.com/thomvaill/log4brains) which seems to be fully featured enough to use easily and provides a setup process.

We would need to update existing Github Issue and PR templates to include a note about ADRs, and consider / suggest if one would be appropriate for the given Issue or PR.

We do not have to publish the resulting built static site that the Log4Brains tooling provides. It is also still possible and easy to use ADRs manually.

We could trial using ADRs and Log4brains in this repo.

What might this look like?

Here's one example of what ADRs look like: https://github.com/opinionated-digital-center/architecture-decision-records/blob/master/docs/adr/index.md

---

I had written this proposal in a longer form with more explanantion but lost it during a BSOD, but more succinct might be better anyway.

[gregsdennis]

So is this an ADR on whether we should adopt ADRs?

[Julian]

Depends on if we had a GitHub discussion to adopt GitHub discussions.

[Relequestual]

Actually, your first ADR is stating you decided to adopt ADRs!

[jdesrosiers]

Is it really necessary to use some special tool for this? What does MADR or log4brains get us that we don't get from standard Github Markdown and an agreed upon template? I'd rather keep the tool chain simple unless there's a really good reason to adopt something new.

[Relequestual]

MADR is an agreed on markdown template that will work within GitHub Markdown rendering.

I agree, we don't need use a specific tool. We don't need to agree on that here (But at least I've documented the results of my research now).

There's no reason we couldn't later start using it to make the records more accessible.

The built site would make it easier to see an overview, showing a timeline and making the status of each ADR easy to see.

[karenetheridge]

standard Github Markdown and an agreed upon template

Judging from https://github.com/opinionated-digital-center/architecture-decision-records/blob/master/docs/adr/index.md, that seems to be what we have here. It looks like a way of keeping track of proposals as they graduate to accepted/rejected, like Python's PEPs and IETF's RFCs.

If it doesn't impose a burden on participation (e.g. "you can't provide an opinion unless you read these documents first and follow this process exactly") then I'm in favour of trying out a process that makes it easier to track all the balls in the air, because there are a lot of them. Good ideas often end up dying in the github issues queue because there's so many items in there.

However, I wonder if we could achieve similar goals by better use of the existing tools -- e.g. more use of labels, creation of storyboards for ideas in various categories, etc.

[Relequestual]

I don't believe it would impose a burden.
I'm only intending this to be used by our teams or those with a sudden high level of interest in something particular. I'm not expecting every new suggestion by new contributors to use this format, it would be too burdensome on both sides and not what they are for.

I agree we could do labels better. I took a fair amount of time to try and establish some order and meaning, but I feel I only made things slightly better. I think a lot more value can come through automation.

GitHub Projects (storyboards, swimlanes, columns of cards...) is something we might be able to utilise. @kinlane has started a general board for the OpenAPI Initive to allow others to see the moving parts which aren't easily otherwise visible. I think we could use the same, and (iirc) Kin has offered to support us in this, but I'd want to start another Discussion here to proprose and scope it (and be clear we're collectivly OK with giving Kin admin access, which otherwise might not look great given he's my boss).

@karenetheridge If you have any ideas about either how we can better use labels or Projects, please do start another discussion, even if the ideas aren't fully formed. I hope Discussions here can be a sounding board! =]

[jdesrosiers]

I agree that this is mainly something that our team.

I'm not sure we need much process around ADRs. Once we capture our principle design decisions, they should not change or be added to frequently. There shouldn't be many ADRs. The JSON Schema architecture is/should-be very simple.

[Relequestual]

I agree, there should be few.

I also want to use ADRs for other repos, such as this community one, and tests, especially when we find time to expand the test format!

[Relequestual]

I see no objections to this, and several people in favour.
There is concern on overtooling, so let's keep it simple.

I'll mark this as conclucded and create an Issue.

[MikeRalphson]

Just a note that I also think this is a good initiative, and am very 👀 on how it works out for this community.

[Relequestual]

Issue created: #20