Record Architecture Decisions — to scale to many people + many timezones

Wim Leers → credited effulgentsia → .

Wim Leers → credited jessebaker → .

Wim Leers → credited lauriii → .

Wim Leers → credited tim.plunkett → .

https://git.drupalcode.org/issue/experience_builder-3454669/-/blob/34546... looks perfectly readable in the GitLab UI, so … going ahead and merging this rather than waiting for explicit repeated +1s — assuming the "yep, let's try it" reactions from the 4 mentioned people are sufficient to go ahead.

Another possible home for the ADRs is the project's gitlab wiki. I think it's available to our poejcts but not sure if our unique contrib flow would work well with them. Gitlab does create a new repo just for the wiki, all changes to wiki are recorded as commits, and it supports markdown so overall sounds like it could work?

One small suggestion, do not ever edit an accepted record. Only make cosmetic changes to it. If you need to change it, deprecate it and write a new one. Write why you are deprecating it on the new one. Links back and forth should be present in both ADRs.

WRT #12 we have seen much better results when the ADRs are in the repo. In our experience, putting them as close as possible to the code helps developers maintain them.

#12: see #13 — @e0ipso wrote what I was thinking 😄

#13: +1 to never editing accepted CRs. Thanks for the advice! ❤️

This is great to see! I think your current blog posts could be good ways to highlight or announce new ADRs, since I don't see an RSS feed or similar coming out from GitLab.

If you do decide you want to generate a site - we're actually in the process of rebuilding ours in 11ty. We're hoping its done in the next month or so. It's already quite an improvement on build time and developer experience than Gatsby. So, please reach out if you could use that so you don't have to rebuild later unless you want to.

As far as editing ADRs go, we are a little more flexible than "cosmetic" changes. Let's say that a drush command changes names in our example docs. In that case, we wouldn't write a new one since the decision itself hasn't changed - just the implementation. But you have lots of room to try and learn given this is the first time this is being used in core-adjacent development.

This is great to see! I think your current blog posts could be good ways to highlight or announce new ADRs, since I don't see an RSS feed or similar coming out from GitLab.

💯

If you do decide you want to generate a site

I mean … if we can get that generated from within GitLab CI and host it on GitLab Pages (much like 📌 CI: host static version of UI in GitLab Pages Fixed ), then I'd welcome an MR with open arms! 😄

Let's say that a drush command changes names in our example docs […]

That wouldn't change the meaning of the decision though, that's just keeping names in sync. I'd call that "cosmetic" too 🤓 But potato, potahto I guess 😄

But you have lots of room to try and learn given this is the first time this is being used in core-adjacent development.

💯 — and I'll continue to very much welcome your advice!

P.S.: retroactively crediting both of you, @e0ipso and @deviantintegral, because you've both influenced this! 🙏😊