Skip to content

Re-thinking the discussion process #285

Closed

Description

@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 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.
  • 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

Activity

  1. self-assigned this
    on Oct 16, 2024
  2. PaulaPaul commented on Oct 16, 2024

    @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!

  3. mhdawson commented on Oct 22, 2024

    @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.

  4. UlisesGascon commented on Oct 22, 2024

    @UlisesGascon
    MemberAuthor

    PR ready: #291

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions