Rationalize Protocells content between cells/_index.md and goals.md

Thong Kuahrequested to merge
protocells_rationalization into main

Why is this change being made?

When the Protocells page was merged into the Cells design document, the "why" and the goals ended up written twice, in slightly different words. Readers had to guess which version was current.

This MR keeps each idea in one place. The goals move to the goals page, since they apply to all of Cells. The Protocells section keeps only its three pillars, now as a table.

Regions is not part of Protocells, nor Cells so they move to Non-Goals.

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
    • The when to get approval handbook section explains when DRI approval is required
    • The who can approve handbook section explains how to identify the DRI
    • If the MR does not require DRI approval, consider asking someone on your team, such as your manager.
    • The approver may merge the MR. If they approve but don't merge, you can merge.
  • 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
    • Division: If the update affects your division, share the MR in your division 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

Commits

  • Restructure the Protocells pillars prose into tables

Replace the three bold-paragraph pillar descriptions with two tables: an introductory table with Pillar, Purpose, and Result columns, and a second table carrying each pillar's supporting details. The missing-reference rendering examples for the Organizations pillar are condensed into a single sentence covering both the source and target cell cases. All links are preserved.

  • Rename the third Protocells pillar to Cells Infrastructure

The third pillar was named "Cells" and linked to the Cells design document when Protocells was a standalone page. After the merge into cells/_index.md that reference became circular, so rename the pillar to "Cells Infrastructure" and link it to the Cells Infrastructure design document, which covers deploying Cells on GitLab.com. Update the Summary's component list and the mermaid diagram's subgraph label to match.

Also remove the pillars diagram, as the page is getting too long

  • Rationalize Protocells content between cells/_index.md and goals.md

Deduplicate and restructure the Protocells content that was merged into cells/_index.md:

  • Move the Motivation prose (monolith scalability bottleneck and the four horizontal-scalability bullets) into goals.md's Goals section, reworded from "Protocells" to "The Cells architecture", since it motivates the entire Cells program rather than one iteration.
  • Combine the six Protocells goals into those four bullets in goals.md (Organization Isolation and cross-organization public APIs under Logical Isolation; multiple Cells and the one-to-one Self-Managed/Dedicated mapping under Physical Distribution; relieving the legacy cell's database under Scalability; deployment model parity under Feature Parity), and remove the now-redundant Goals subsection from the Protocells section.
  • Defer goals matching Protocells non-goals: merge the "Regions" goal with the "Enables support for Regions" requirement and move it, together with "Re-balancing of Cells", into goals.md's Non-Goals section, removing their Requirements table rows. The #regions anchor is unchanged, so inbound links still resolve.
  • Carry the remaining Protocells non-goals (Global Admins, global settings) into goals.md's Non-Goals, and remove the Non-Goals subsection from the Protocells section. Multi-Cloud support is covered by the moved Regions section; the "detailed implementation specifications" bullet was doc-scoping boilerplate and is dropped.
  • Drop the "Alternative Solutions > Multiple Independent Instances" subsection; it was generic pros/cons already covered in spirit by goals.md's non-goals.
  • Promote "Architecture overview" back to a top-level section; it describes the general Cells architecture and had been left nested inside the Protocells section by the merge.
Edited by Thong Kuah

Merge request reports