Re-thinking the discussion process

[UlisesGascon]

I love this space that we have to discuss and bring new ideas to the table. So far, it's working well, but I believe we can make some small changes to make it even more awesome^TM.

Current Challenges

So far, once a discussion is solved and we arrive at a conclusion, we don't always provide a summary. This can result in re-entering the same discussion later, or we forget the last agreement made, causing us to revisit the same issue. This is especially problematic if different people are involved in the repeated discussions, as they may miss important context from the previous conversation.

We also have dozens of issues in this repo that are in an unknown state, so we might want to use proper labels to represent different stages of the discussions. Of course, we should also do some cleanup and close a few of them.

Potential Improvements

For decision-making, we could use a light implementation of the Architecture Decision Record (ADR). We can store these decisions as markdown files in this repo and revisit them when needed. The goal is to record the motivations behind decisions, the alternatives we explored, etc., so new contributors can have a better understanding of the project's history. I can create a basic example if we agree this is a good idea.

For labeling, I propose the following:

• New – For newly created issues
• Waiting – When discussions are blocked due to external factors or waiting for POCs, etc.
• Active – For discussions currently in progress
• Waiting for ADR – Waiting for an ADR PR
• Discarded – The proposal did not succeed

cc: @expressjs/triagers @expressjs/express-tc @expressjs/security-wg

[PaulaPaul]

In my consulting jobs I always introduce ADRs!
It's good to have a process for a regular review of completed ADRs (every 3-6 months, or longer, depending on how many decision records are created). That is a good way to learn from the decisions made months/years ago. It can be helpful to revisit those decisions to record 'lessons learned'. Sometimes that results in new decision records that refer back to the original decision.

This process is very valuable for onboarding, and to remind maintainers what we were thinking months (or years) ago.

Some tips:

• Always define the 'scope' of the ADRs (for example 'These Repos...' or 'all activities that support the xxxxx Project', or 'everything within this Org, except for xxxx')
• Define 'who can create an ADR'. It can be helpful to state that anyone can propose an ADR, and define the process by which it becomes final / merged
• Define some kind of schedule for regular discussion of in-process ADRs (depending on how many you generate, and how urgent), or define the way that people can request a live discussion
• Define some schedule for review of existing ADRs to capture lessons learned and adjust decisions based on new information (for example, every six months or year), and make that a public discussion (great education opportunity)

Hope this helps!

[mhdawson]

In Node.js we don't have a formal ADR process, but for important decisions I often try to add what was agreed to the documentation somewhere. Either in a doc the https://github.com/nodejs/node/tree/main/doc/contributing or the doc in the admin or TSC repos.

However its done I think documenting somewhere is really helpful both as a place to remember what was agreed and as a place to point people to read more about a topic/how things work.

[UlisesGascon]

PR ready: #291