Here it might be an option that we also provide code samples how the other implementations would look like. I did not add it to the README yet, but would probably be interesting.

This could be useful exactly in the cases of introducing new library / pattern.

I hope it is clear enough that I do not mean that every new gem or NPM package needs an ADR. It should be that if we do something like switch from Angular to Turbo, etc that this should become an ADR.

Only future will tell how clear this was. Taking the dry-rb example: AFAIK it was introduced as a "test balloon" in storages and now it lives an isolated life there.

To me the question would be at which point we start the ADR process:

• before launching the test balloon
  • Good, because it ensures that the decision and its drivers are documented properly
  • Bad, because it could lead to process fatigue
• after launching the test balloon
  • Good, because ideas can be quickly validated/falsified
  • Bad, because after the fact people are less likely to care about proper documentation

I guess it depends a bit. If we had had an ADR that specifies that our Service objects use our own service classes, than introducing dry-monads would have needed an ADR that replaces the old one. In that process the developers would have to make a case why the new solution is better than the old one. And we would have to make a decision to switch our entire codebase.

But I get your point. We need to be allowed to play around with technologies. But at some point we will have to make a decision if the new technology is a viable way forward or not. And if we decide either way one will have to bite into the sour apple and depending on outcome in this case

a) Get rid of our old service classes in the entire codebase and replace them with dry-monads
b) Get rid of the "test balloon" and replace dry-monads with our old service classes

But than we also have to agree that there must be time set aside to go through with these.

This would be something like introducing hocuspocus. This needs to be considered in the deployment process, etc, so it should at least be discussed how SaaS, self-hosted, docker, etc deployments work.

To me revisited suggests changing the decision which contradicts immutability.

Also is it worth mentioning the way (removal, marking them so, …) to handle outdated decisions?

The process is mentioned in the readme, i don't think it needs to be part of the template. WDYT?

About revisiting, yeah, I agree, let's word this differently. The process is that it can be superseded and be archived. See the README for details.

There should be an "escape hatch" for when ADR decisions might (occasionally) need to be overridden. I'm not sure if we need a separate section for this, but it could look like:

Exceptions

• Exceptions are allowed when the ADR is impractical, incomplete, or counterproductive in a specific context.
• Any exception should be explicit and visible (for example: noted in the pull request, code comments, or follow-up ADR).
• Exceptions and recurring friction are treated as input to the feedback loop, and may result in clarifying, amending, or superseding the ADR.
• An ADR should never be used as a disciplinary tool; its purpose is alignment, not enforcement.

I kind of disagree. When we give escape routes, we are talking about guidelines and not rules. For example when we decide to use Angular as our Frontend Framework, a developer should not be allowed to just add a React component and comment in the PR with "made more sense here". In this case, the ADR that forces us to use Angular should be archived and superseded by another one that allows Angular and React for certain cases.

its purpose is alignment, not enforcement

While I like this, it feels like a slippery slope to me. Essentially we can ignore ADRs whenever we don't like their impact.

It's a bit like "asking for forgiveness" instead of "asking for permission".

(I am not saying we shouldn't allow exceptions, but I am not sure whether we should formally put the option for exceptions in)

(I am not saying we shouldn't allow exceptions, but I am not sure whether we should formally put the option for exceptions in)

If people do find it difficult to adhere for whatever reason, then it's much better if those reasons are visible and documented. We don't want devs slipping in changes surreptitiously because they find one of our ADR decisions too rigid or the process too arduous. We do want our process to reflect reality!

It's a bit like "asking for forgiveness" instead of "asking for permission".

FWIW, when in doubt, I always opt for the first.

a developer should not be allowed to just add a React component and comment in the PR with "made more sense here".

That's clearly not an acceptable level of documentation! I've actually opened a couple PRs that use Primer React components - primarily for discussion / Proof of Concept. I wouldn't want that ability to experiment to be curtailed!

The onus would be on me to elaborate a bit. Perhaps:

"This is an experiment that investigates exposing React components as custom elements in order to take advantage of the improvements only currently available in the Primer implementation.

@akabiru

I think it will be a question of how detailed we will go with ADRs. I don't think we will have tons of them covering every little detail of how we write code. Just important ones, like introducing new technologies (like Primer View Components for example).

Actually, Primer View Components are a very good example. Since their introduction, we have not added new pages to our code that use SPOT. Whenever we touched something we thought about migrating it to Primer when it was feasible. So this is the perfect example of what would be handled in an ADR and how it is enforced.

If we did an ADR that enforces for example Angular as our frontend technology, then I personally would say, you can experiment with React, sure, but if you want to merge it into the codebase, the ADR has to be adjusted before we do this.

Same thing goes for if we say in an ADR that Service objects are done using our Service class, then it is forbidden to introduce something like dry-monads into the codebase until the ADR has been replaced and explicitly allows for either both or only the new one.

One can experiment in PRs and make a case for why the ADR needs to be changed.

But we all know too well, if we start violating something like this we agreed on in one place with the intent "let's just add this one React thing here, see how it goes, and in a few weeks we will remove it" ... That then gets fogotten and stays in there forever until somebody comes along and is wondering why there is React in here, if we clearly state in an ADR that we do not use React.

I am with Klaus on this one to be honest. Otherwise ADRs risk to become pointless. However, let's also be clear that it's in the end on the ADR to allow for certain exclusions.

I find it hard to discuss @myabc's use of React components right now, because an ADR forbidding to do so, doesn't exist. What would our ADR look like? Does it say "we only use tool X" or does it say "we primiarily use tool X" or "in this specified area we use tool X"?

If we don't treat ADRs as binding agreements among developers, then I am not sure why we should do them.

An ADR should never be used as a disciplinary tool; its purpose is alignment, not enforcement.

And maybe to elaborate on terms such as "binding agreement", "disciplinary tool" and "enforcement". So far I didn't read anything about fines to be paid or jail time to be incurred, if you violate an ADR. So I don't see any enforcing functions included.
It's a gentlemen's agreement that we do not violate the rules we set out to play by and I think there will be plenty of violating those rules happening even without us already writing down every possible way that we do not want to follow them beforehand.

So I don't see any enforcing functions included.

Well, it states in the template that we should however possible use "enforcement" tools like Rubocop, Danger, etc. While those do not fine developers, there should be as much enforcement as possible.

For example, when we add a rubocop rule that will enforce an ADR, there should at least be a discussion in the pull request, when that rule is explicitly disabled for a file that was added.

Does it say "we only use tool X" or does it say "we primiarily use tool X" or "in this specified area we use tool X"?

Primer View Component is the default. Use Primer's View Compnent implementation unless you have a very good reason not to.

I guess this could be codified in the relevant ADR rather than ADR 0001.

I am wondering whether this will be true. Once we have our first 20 ADRs that are sorted by time of introduction, I am really wondering whether they are:

• quick to grasp
• giving a proper understanding of the system architecture

This sounds like the intended/hoped for outcome.

In other words (no clue if this is formally correct):

I see the point. The question is, how deep you have to go into the ADR to understand it. The points Decision Outcome and Consequences are the sections where somebody who just wants to understand what the decision is, can basically stop reading. If for example a new developer wants to dive deeper and see for example why we chose Turbo as our frontend technology, they can continue reading on.

Maybe there should also be a one pager that looks something like.

We use Turbo as our frontend technology

Bla bla bla .. explanation. For further details, see ADR-0042

We use Grape for our API

Bla Bla Bla .. explanation. For further details, see ADR-0001

So we have something to point people to so that they can quickly grasp the outcomes, without needing to read through many pages of details.

I like this idea.

It will work sufficiently for "tool choices" at least. Once you get to processes and patterns that need explaining, I think there is the part where you still need to explain the pattern as part of the ADR.

E.g. some of my later comments in this PR are about our implementation choices for ADRs. That's something people should also read.

edit: After being nearly done, with the review, I could log more than an hour on ADR-0000 for the initial review alone

This question might sound stupid, but how do we handle race conditions?

I.e. since ADRs are accepted in pull requests, it's easily possible that the latest ADR in dev is 0000, but there are already two PRs that each want to introduce a new ADR. edit: Just now read that the answer is "coordinate", adjacent question below remains valid as far as I can tell.

Adjacent question: Do rejected ADRs get a number and a place in the docs as well? (I can see good and bad for both ways)

Note that there is no rejected state. When an ADR is suggested and the team decides against it, the PR is closed and it is not added to the repo.

As for the conflict ... We will not be adding 100s of ADRs. If two ADRs come in at the same time, I count on mature developers agreeing that one has to rename theirs.

Something that I notice: Some of the process parts are restricted to OpenProject GmbH employees. I think practically this is fine, since I've not seen any outside contribution/contributor yet that had a significant enough impact that they'd ever need an ADR for their contributions.

Still it feels like a violation of the open aspect in open source, that certain parts of the development process for this tool are by design reserved to employees.

I think it is us setting the agenda here.

Not sure what you mean, maybe I wasn't clear enough about my concern:

Right now the process requires mentioning a private matrix channel and putting the topic up on an agenda of a private meeting. This excludes the public from this kind of change on a process level.

As I said, this is probably not a practical problem, since I've not seen any outside contributions of a magnitude that they would require (or be interested in) changing ADRs. Still we should be aware that this is a barrier we are adding here.

I think we should design the process so that it works for us, the company. If we ever see outside contribution in a relevant mass, where it would make sense that people would attend our dev discussion meetings, we will have to set up a lot of different processes anyway. I think tackling this now might be premature optimization for a case that will likely never happen.

If it comes to this, that an outside contributor is heavily invested in the process, we can invite them to meetings.

Said every bureaucrat about every bureaucratic process ever. Most processes were born out of good intentions, some people even pave roads with good intentions.

I still think that we should try it out and see whether they help, but reading a line like this is literal rage bait for me xD