You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 issues
Waiting – When discussions are blocked due to external factors or waiting for POCs, etc.
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)
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.
Activity
PaulaPaul commentedon Oct 16, 2024
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!
mhdawson commentedon Oct 22, 2024
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 commentedon Oct 22, 2024
PR ready: #291