ADR Suggestion Maintain an ADRs Index for Onboarding and Discoverability

[AndrewSazonov]

Organization-wide Architectural Decision Records (ADRs) and ADR suggestions in the EasyScience ecosystem are captured as GitHub Discussions.

While this provides flexibility and preserves discussion history, it makes it difficult for:

• New developers to gain an overview of architectural and procedural decisions
• Existing developers to quickly locate previously agreed decisions

Currently, there is no single entry point that summarizes what decisions exist across the organization.

Suggestion

Introduce a centralized ADR index file (ADRs.md) maintained in the EasyScience GitHub organization configuration repository:
easyscience/.github

The file serves as a Table of Contents (TOC) for all ADRs and ADR suggestions across the EasyScience organization.

Requirements for ADRs.md

The index must:

• Group ADRs by topic (e.g., CI/CD, Documentation, Naming, Architecture, etc.)
• Contain links to the corresponding GitHub Discussion
• Include both accepted ADRs and ADR Suggestion discussions
• Replace ADR Suggestion entries with the final ADR once the decision is accepted

Question

• Should the same ADR indexing procedure be applied to all main EasyScience projects in their respective home repositories (easyscience/diffraction, easyscience/reflectometry, easyscience/imaging, etc.)?
• Or should a single ADRs.md index in easyscience/.github list both organization-wide ADRs and project-specific ADRs?

[henrikjacobsenfys]

I think this is a good idea. Maybe test it out on corelib and the other shared libs, then make individual decisions for the other repositories?

I think it's best to keep the ADR.md files project specific. I think it would be confusing/wasteful to have to look through a list of ADR suggestions for EasyDynamics when trying to figure out how corelib works.

[rozyczko]

Would an easier-to-grep and easier-to-maintain solution be to just assign appropriate categories to ADRs for each topic?

GitHub already allows creating discussion categories. Splitting ADR categories into the topics immediately allows narrowing down the display of the relevant ADRs and helps with finding the right one(s). You just click on the category and get a list of all ADRs comprsing it.

Adding an index is an unnecessary complication and maintenance cost.

[AndrewSazonov]

This indeed looks simpler and would not require extra maintenance. However, if we split ADRs this way, the list of categories may become a bit too ADR-oriented over time. We will likely end up with several ADR sub-categories, comparable in number to all other categories.

In addition, this would slightly break consistency, since the other categories are not split in the same way.

For these reasons, a lightweight ADRs.md that mainly acts as a TOC still looks more convenient to me as a way to provide a clean, one-page overview of all ADRs. Being able to control the order on that page would also allow us to present ADRs in a logical reading order, rather than alphabetically or purely by time, which I think is much easier to follow, especially for onboarding.

To make sure the index is kept up to date, we could explicitly define this step in the existing Protocol for creating an ADR #15.

[seventil]

I'm all for indexed and navigatable menus for easy access to documentation such as ADR. But I also think that categorizing documentation like that might create a too robust structure. I suggest that we (on top of some initial categories) have tags in ADR/ADR Suggestions, to add some of the categorization flexibility:
• if we get too many ADRs with the same tag - suggests creation of a new category
• category has a small amount of ADRs - suggests that it shouldn't be a separate category, but maybe just a tag
• a category has too many ADRs - suggests further splits based on tags

I think that way we'll have meaningful categories for adr navigation

[AndrewSazonov]

I think this is a good suggestion for how new category names could naturally emerge over time, based on the actual number and types of ADRs, rather than trying to define all possible categories from the beginning.

I don’t currently see a built-in mechanism for adding tags to discussions, but we could probably introduce a lightweight, text-based convention (for example, in a dedicated subsection of the discussion description)?

That said, I’m wondering how you imagine this working in practice. Should the ADR suggestion author add one (or possibly multiple) tags? And should those be chosen freely, or selected from a predefined (but larger) set than the initial categories? If chosen freely, how do we guarantee that we do not end up with multiple different tags meaning the same thing?

Also, if a new ADR suggestion does not fit any existing category, where should it live initially? Something like “General” category as a starting point? Or do you suggest keeping such ADRs uncategorised until there are enough of them to justify creating a category? However, grouping them as uncategorised would naturally create an “Uncategorised” category anyway.

[damskii9992]

I think I prefer this over maintaining an ADR.md file.

In regards to the tags, we can just use the [area] labels that we already defined for issues/PR's?

I would also like to add that I don't think we should categorize ADR suggestions. We should (hopefully) never have so many open suggestions that they warrant any kind of grouping to navigate.