MR: Pending <!-- The first line of this issue description must be one of the following: 1. `MR: Pending` 2. `MR: <MR link with trailing +>`, 3. If there are multiple MRs: ``` MRs: - <MR 1 link with trailing +>` - <MR 2 link with trailing +>` - ... ``` 4. `MR: No MR` ...and the first description line of the MR should be `Issue: <Issue link with trailing +>` For more context, see: https://about.gitlab.com/handbook/engineering/development/dev/create/ide/index.html#relationship-of-issues-to-mrs --> <!-- The following sections should be filled out as part of the refinement process before the issue is prioritized. For more context, see: https://about.gitlab.com/handbook/engineering/development/dev/create/ide/#2-pre-iteration-planning-meeting --> ## Description Refactor Remote Development Blueprint into Architecture Decision Record format ## Acceptance Criteria TODO: Fill out (required) - [ ] [Describe what must be achieved to complete this issue.] - [ ] [Describe another requirement needed to complete this issue.] - [ ] [Add additional acceptance criteria as needed.] ## Technical Requirements [Discussion from internal slack thread](https://gitlab.slack.com/archives/CJ4DB7517/p1713529479593399?thread_ts=1713419922.899049&cid=CJ4DB7517): --- grzegorz 10 days ago I haven't read the whole thread here, but wanted to point you to the latest development in writing design docs / blueprints. We adopted ADRs in a way that there is a "Decisions" section that contains immutable ADRs, and the main (very simple) page of the blueprint is always being updated along with the latest ADR. This makes the design doc always up to date, even if the ADRs are becoming outdated (then we indicate that the ADR has been changed on the list). Here is the example: https://gitlab.com/gitlab-org/architecture/gitlab-gcp-integration/design-doc (edited) ---- grzegorz 10 days ago The main page there probably still needs some updates, but with immutable ADRs it becomes much more manageable. ---- Chad Woolley 9 days ago > We adopted ADRs in a way that there is a “Decisions” section that contains immutable ADRs, and the main (very simple) page of the blueprint is always being updated along with the latest ADR. This makes the design doc always up to date, even if the ADRs are becoming outdated (then we indicate that the ADR has been changed on the list). Here is the example: https://gitlab.com/gitlab-org/architecture/gitlab-gcp-integration/design-doc This seems like a great idea. Loose coupling and high cohesion applied to documentation. @grzegorz - what would you think of migrating an existing blueprint like the Remote Development blueprint to this approach? How might you go about that? :+1: 1 ---- grzegorz 9 days ago @Chad Woolley If I wanted to rewrite the existing Remote Development design doc I would keep the "Vision" section (probably rewriting it a bit to make it more relevant long-term) and would add "Overview" and "Decisions" section. The "Overview" would be a distilled content from "Decisions", describing the current state, updated each time when we add a new ADR. Then I would go back to see what fundamental design decisions have been made, and I would document those to create an immutable register of the decisions. Then I would remove almost everything else (depending on the common sense). Does it answer your question? (edited) :+1::skin-tone-3::+1: 3 --- Chad Woolley 8 days ago Yes it does, thanks. Cc @Vishal Tak --- ## Design Requirements TODO: Fill out or delete (optional) [If applicable, please provide a link to the design specifications for this feature/enhancement.] ## Impact Assessment TODO: Fill out or delete (optional) [Please describe the impact this feature/enhancement will have on the user experience and/or the product as a whole.] ## User Story TODO: Fill out or delete (optional) [Provide a user story to illustrate the use case for this feature/enhancement. Include examples to help communicate the intended functionality.] <!-- Replace with other type, e.g. bug or maintenance, if appropriate --> <!-- Replace with other subtype if appropriate --> <!-- By default, all issues start in the unprioritized status. See https://about.gitlab.com/handbook/engineering/development/dev/create/ide/#-remote-development-planning-process --> <!-- For simplicity and to avoid triage bot warnings about missing workflow labels, we will default to issues starting at the refinement phase -->