Skip to content

Embed decision making process in Architecture Design Workflow

Fabio Pitino requested to merge docs/embed-decision-making-in-architecture-design-workflow into master

Why is this change being made?

Architecture design docs are important artifacts that allow engineers and leadership to collaborate on a complex problem to solve. Often, during this collaboration process we found that it's not clear why we chose a specific solution. Context may be buried in issues, Slack threads or Google Docs and we did not capture, in the design doc, enough details on the "why".

This MR also aims to address the problem of having multiple end-to-end proposals in design docs which make it difficult to understand differences between the proposals, what tradeoffs are at play,. The reality is that a proposal is made by a specific set of tradeoffs. We can instead work on a single common proposal by breaking it down into various aspects and use a decision making process to gain a common context and being all on the same page.

This change is inspired by conversations in gitlab-org/gitlab#424486 (comment 1547459154)

Next steps: Update the template to reflect the changes in this MR: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/architecture/blueprints/_template.md?plain=1

Author and Reviewer Checklist

Please verify the check list and ensure to tick them off before the MR is merged.

  • Provided a concise title for this Merge Request (MR)
  • Added a description to this MR explaining the reasons for the proposed change, per say why, not just what
    • Copy/paste the Slack conversation to document it for later, or upload screenshots. Verify that no confidential data is added, and the content is SAFE
  • Assign reviewers for this MR to the correct Directly Responsible Individual/s (DRI)
    • If the DRI for the page/s being updated isn’t immediately clear, then assign it to one of the people listed in the Maintained by section on the page being edited
    • If your manager does not have merge rights, please ask someone to merge it AFTER it has been approved by your manager in #mr-buddies
    • The when to get approval handbook section explains the workflow in more detail
  • For transparency, share this MR with the audience that will be impacted.
    • Team: For changes that affect your direct team, share in your group Slack channel
    • Department: If the update affects your department, share the MR in your department Slack channel
    • Company: If the update affects all (or the majority of) GitLab team members, post an update in #whats-happening-at-gitlab linking to this MR
Edited by Fabio Pitino

Merge request reports