Open UlisesGascon opened 5 days ago
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:
Hope this helps!
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 awesomeTM.
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 issuesWaiting
– When discussions are blocked due to external factors or waiting for POCs, etc.Active
– For discussions currently in progressWaiting for ADR
– Waiting for an ADR PRDiscarded
– The proposal did not succeedcc: @expressjs/triagers @expressjs/express-tc @expressjs/security-wg