From f18b5daab861f2490575403f7f8c7ba670e7752a Mon Sep 17 00:00:00 2001 From: Thomas Randolph Date: Wed, 11 Oct 2023 19:45:53 -0600 Subject: [PATCH 1/4] Add mermaid chart only currently in raster image format --- .../merge_request_concepts/diffs/frontend.md | 152 +++++++++++++++++- 1 file changed, 148 insertions(+), 4 deletions(-) diff --git a/doc/development/merge_request_concepts/diffs/frontend.md b/doc/development/merge_request_concepts/diffs/frontend.md index ff163050e1f2a7..7109ad2a77b1be 100644 --- a/doc/development/merge_request_concepts/diffs/frontend.md +++ b/doc/development/merge_request_concepts/diffs/frontend.md @@ -23,10 +23,154 @@ The Vue app for rendering diffs uses many different Vue components, some of whic with other areas of the GitLab app. The below chart shows the direction for which components get rendered. -NOTE: -[Issue #388843](https://gitlab.com/gitlab-org/gitlab/-/issues/388843) is open to -generate a Mermaid graph of the components diagram. An image version of the -diagram is available in the issue. +The following legend may be useful to assist in reading the chart: + +| Legend item | Interpretation | +| ----------- | -------------- | +| `xxx~~~` | Indicates a shortened directory path name. Can be found in `app/assets/javascripts`, and omits `0..n` nested folders | +| Rectangular nodes | Files | +| Oval nodes | Plain language describing a deeper concept | +| Double-rectangular nodes | Simplified code branch | +| Diamond nodes | Branches that have only two options | +| Pendant/Banner nodes (left notch, right square) | A parent directory to shorten nested paths | +| `./` | A path relative to the closest parent directory pendant node. Non-relative paths nested under parent pendant nodes are not in that directory | +| Circle nodes | Branches that have 3+ possible options. The content of the circle indicates psuedocode that is tested to decide the branch direction | + +```mermaid + flowchart TB + classDef code font-family: monospace; + + A["diffs~~app.vue"] + descVirtualScroller(["Virtual Scroller"]) + codeForFiles[["v-for(diffFiles)"]] + B["diffs~~diff_file.vue"] + C["diffs~~diff_file_header.vue"] + D["diffs~~diff_stats.vue"] + E["diffs~~diff_content.vue"] + boolFileIsText{isTextFile} + boolOnlyWhitespace{isWhitespaceOnly} + boolNotDiffable{notDiffable} + boolNoPreview{noPreview} + codeShowChanges[["Show button to "Show changes""]] + dirDiffViewer>"vue_shared~~diff_viewer"] + F["./viewers/not_diffable.vue"] + G["./viewers/no_preview.vue"] + H["./diff_viewer.vue"] + I["diffs~~diff_view.vue"] + boolIsRenamed{isRenamed} + boolIsModeChanged{isModeChanged} + boolFileHasNoPath{hasNewPath} + boolIsImage{isImage} + J["./viewers/renamed.vue"] + K["./viewers/mode_changed.vue"] + descNoViewer(["No viewer is rendered"]) + L["./viewers/image_diff_viewer.vue"] + M["./viewers/download.vue"] + N["vue_shared~~download_diff_viewer.vue"] + boolImageIsReplaced{isReplaced} + O["vue_shared~~image_viewer.vue"] + switchImageMode((image_diff_viewer.mode)) + P["./viewers/image_diff/onion_skin_viewer.vue"] + Q["./viewers/image_diff/swipe_viewer.vue"] + R["./viewers/image_diff/two_up_viewer.vue"] + S["diffs~~image_diff_overlay.vue"] + codeForImageDiscussions[["v-for(discussions)"]] + T["vue_shared~~design_note_pin.vue"] + U["vue_shared~~user_avatar_link.vue"] + V["diffs~~diff_discussions.vue"] + W["batch_comments~~diff_file_drafts.vue"] + codeForTwoUpDiscussions[["v-for(discussions)"]] + codeForTwoUpDrafts[["v-for(drafts)"]] + X["notes~~notable_discussion.vue"] + + class codeForFiles,codeShowChanges,codeForImageDiscussions code; + class codeForTwoUpDiscussions,codeForTwoUpDrafts code; + %% Also apply code styling to this switch node + class switchImageMode code; + %% Also apply code styling to these boolean nodes + class boolFileIsText,boolOnlyWhitespace,boolNotDiffable,boolNoPreview code; + class boolIsRenamed,boolIsModeChanged,boolFileHasNoPath,boolIsImage code; + class boolImageIsReplaced code; + + A --> descVirtualScroller + A -->|"Virtual Scroller is + disabled when + Find in page search + (Cmd/Ctrl+f) is used."|codeForFiles + descVirtualScroller --> codeForFiles + codeForFiles --> B + B --> C + C --> D + B --> E + + %% File view flags cascade + E --> boolFileIsText + boolFileIsText --> |yes| I + boolFileIsText --> |no| boolOnlyWhitespace + + boolOnlyWhitespace --> |yes| codeShowChanges + boolOnlyWhitespace --> |no| dirDiffViewer + + dirDiffViewer --> H + + H --> boolNotDiffable + + boolNotDiffable --> |yes| F + boolNotDiffable --> |no| boolNoPreview + + boolNoPreview --> |yes| G + boolNoPreview --> |no| boolIsRenamed + + boolIsRenamed --> |yes| J + boolIsRenamed --> |no| boolIsModeChanged + + boolIsModeChanged --> |yes| K + boolIsModeChanged --> |no| boolFileHasNoPath + + boolFileHasNoPath --> |yes| boolIsImage + boolFileHasNoPath --> |no| descNoViewer + + boolIsImage --> |yes| L + boolIsImage --> |no| M + M --> N + + %% Image diff viewer + L --> boolImageIsReplaced + + boolImageIsReplaced --> |yes| switchImageMode + boolImageIsReplaced --> |no| O + + switchImageMode -->|'onion'| P + switchImageMode -->|'swipe'| Q + switchImageMode -->|"'twoup' (default)"| R + + P & Q & R --> S + S --> codeForImageDiscussions + + R-->|"Rendered in + note container div"|U & V & W + + V --> codeForTwoUpDiscussions + W --> codeForTwoUpDrafts + + %% This invisible link forces `noteable_discussion` + %% to render above `design_note_pin` + X ~~~ T + + %% This invisible link forces the image viewer + %% `v-for` nodes to render at the same vertical layer + %% despite varying nested depths + codeForImageDiscussions & codeForTwoUpDiscussions & codeForTwoUpDrafts ~~~ X + + codeForTwoUpDiscussions --> X + codeForImageDiscussions & codeForTwoUpDiscussions & codeForTwoUpDrafts --> T + + codeForTwoUpDrafts --> Y["TBD: Points to draft_note from text_file branch"] + S --> Z["TBD: Points to note_form from text_file branch"] + + %% Text file diff viewer + I --> TBD +``` Some of the components are rendered more than others, but the main component is `diff_row.vue`. This component renders every diff line in a diff file. For performance reasons, this -- GitLab From d7b99752f92c9090d392c5b7aa9701a76796a29a Mon Sep 17 00:00:00 2001 From: Thomas Randolph Date: Thu, 12 Oct 2023 16:02:55 -0600 Subject: [PATCH 2/4] Finish chart and re-arrange to prevent crossing lines --- .../merge_request_concepts/diffs/frontend.md | 79 ++++++++++++++----- 1 file changed, 59 insertions(+), 20 deletions(-) diff --git a/doc/development/merge_request_concepts/diffs/frontend.md b/doc/development/merge_request_concepts/diffs/frontend.md index 7109ad2a77b1be..3a409b2bea8b38 100644 --- a/doc/development/merge_request_concepts/diffs/frontend.md +++ b/doc/development/merge_request_concepts/diffs/frontend.md @@ -27,14 +27,13 @@ The following legend may be useful to assist in reading the chart: | Legend item | Interpretation | | ----------- | -------------- | -| `xxx~~~` | Indicates a shortened directory path name. Can be found in `app/assets/javascripts`, and omits `0..n` nested folders | +| `xxx~~`, `ee-xxx~~` | Indicates a shortened directory path name. Can be found in `[ee]/app/assets/javascripts`, and omits `0..n` nested folders | | Rectangular nodes | Files | | Oval nodes | Plain language describing a deeper concept | | Double-rectangular nodes | Simplified code branch | -| Diamond nodes | Branches that have only two options | +| Diamond & Circle nodes | Branches that have two (diamond) or 3+ (circle) options | | Pendant/Banner nodes (left notch, right square) | A parent directory to shorten nested paths | | `./` | A path relative to the closest parent directory pendant node. Non-relative paths nested under parent pendant nodes are not in that directory | -| Circle nodes | Branches that have 3+ possible options. The content of the circle indicates psuedocode that is tested to decide the branch direction | ```mermaid flowchart TB @@ -51,7 +50,8 @@ The following legend may be useful to assist in reading the chart: boolOnlyWhitespace{isWhitespaceOnly} boolNotDiffable{notDiffable} boolNoPreview{noPreview} - codeShowChanges[["Show button to "Show changes""]] + descShowChanges(["Show button to "Show changes""]) + %% Non-text changes dirDiffViewer>"vue_shared~~diff_viewer"] F["./viewers/not_diffable.vue"] G["./viewers/no_preview.vue"] @@ -82,9 +82,35 @@ The following legend may be useful to assist in reading the chart: codeForTwoUpDiscussions[["v-for(discussions)"]] codeForTwoUpDrafts[["v-for(drafts)"]] X["notes~~notable_discussion.vue"] - - class codeForFiles,codeShowChanges,codeForImageDiscussions code; + %% Text-file changes + codeForDiffLines[["v-for(diffLines)"]] + Y["diffs~~diff_expansion_cell.vue"] + Z["diffs~~diff_row.vue"] + AA["diffs~~diff_line.vue"] + AB["batch_comments~~draft_note.vue"] + AC["diffs~~diff_comment_cell.vue"] + AD["diffs~~diff_gutter_avatars.vue"] + AE["ee-diffs~~inline_findings_flag_switcher.vue"] + AF["notes~~noteable_note.vue"] + AG["unknown~~publish_button.vue"] + AH["notes~~note_actions.vue"] + AI["notes~~note_body.vue"] + AJ["notes~~note_header.vue"] + AK["notes~~reply_button.vue"] + AL["notes~~note_awards_list.vue"] + AM["notes~~note_edited_text.vue"] + AN["notes~~note_form.vue"] + AO["vue_shared~~awards_list.vue"] + AP["emoji~~picker.vue"] + AQ["emoji~~emoji_list.vue"] + descEmojiVirtualScroll(["Virtual Scroller"]) + AR["emoji~~category.vue"] + AS["emoji~emoji_category.vue"] + AT["vue_shared~~markdown_editor.vue"] + + class codeForFiles,codeForImageDiscussions code; class codeForTwoUpDiscussions,codeForTwoUpDrafts code; + class codeForDiffLines code; %% Also apply code styling to this switch node class switchImageMode code; %% Also apply code styling to these boolean nodes @@ -108,7 +134,7 @@ The following legend may be useful to assist in reading the chart: boolFileIsText --> |yes| I boolFileIsText --> |no| boolOnlyWhitespace - boolOnlyWhitespace --> |yes| codeShowChanges + boolOnlyWhitespace --> |yes| descShowChanges boolOnlyWhitespace --> |no| dirDiffViewer dirDiffViewer --> H @@ -140,15 +166,17 @@ The following legend may be useful to assist in reading the chart: boolImageIsReplaced --> |yes| switchImageMode boolImageIsReplaced --> |no| O + switchImageMode -->|"'twoup' (default)"| R switchImageMode -->|'onion'| P switchImageMode -->|'swipe'| Q - switchImageMode -->|"'twoup' (default)"| R - P & Q & R --> S + P & Q --> S S --> codeForImageDiscussions + S --> AN R-->|"Rendered in - note container div"|U & V & W + note container div"|U & W & V + R --> S V --> codeForTwoUpDiscussions W --> codeForTwoUpDrafts @@ -157,19 +185,30 @@ The following legend may be useful to assist in reading the chart: %% to render above `design_note_pin` X ~~~ T - %% This invisible link forces the image viewer - %% `v-for` nodes to render at the same vertical layer - %% despite varying nested depths - codeForImageDiscussions & codeForTwoUpDiscussions & codeForTwoUpDrafts ~~~ X - - codeForTwoUpDiscussions --> X + codeForTwoUpDrafts --> AB codeForImageDiscussions & codeForTwoUpDiscussions & codeForTwoUpDrafts --> T - - codeForTwoUpDrafts --> Y["TBD: Points to draft_note from text_file branch"] - S --> Z["TBD: Points to note_form from text_file branch"] + codeForTwoUpDiscussions --> X %% Text file diff viewer - I --> TBD + I --> codeForDiffLines + codeForDiffLines --> Z + codeForDiffLines -->|"isMatchLine?"| Y + codeForDiffLines -->|"hasCodeQuality?"| AA + codeForDiffLines -->|"hasDraftNote(s)?"| AB + + Z -->|"hasCodeQuality?"| AE + Z -->|"hasDiscussions?"| AD + + AA --> AC + + %% Draft notes + AB --> AF + AB -->|"mrReviewSubmitComment?????"| AG + AF --> AH & AI & AJ + AH --> AK + AI --> AL & AM & AN + AL --> AO --> AP --> AQ --> descEmojiVirtualScroll --> AR --> AS + AN --> AT ``` Some of the components are rendered more than others, but the main component is `diff_row.vue`. -- GitLab From 5188ff76235e87635982675aa57338035e85ac60 Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Fri, 13 Oct 2023 21:38:42 +0000 Subject: [PATCH 3/4] Remove unneeded line --- doc/development/merge_request_concepts/diffs/frontend.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/development/merge_request_concepts/diffs/frontend.md b/doc/development/merge_request_concepts/diffs/frontend.md index 3a409b2bea8b38..c380f480713bd1 100644 --- a/doc/development/merge_request_concepts/diffs/frontend.md +++ b/doc/development/merge_request_concepts/diffs/frontend.md @@ -203,7 +203,6 @@ The following legend may be useful to assist in reading the chart: %% Draft notes AB --> AF - AB -->|"mrReviewSubmitComment?????"| AG AF --> AH & AI & AJ AH --> AK AI --> AL & AM & AN -- GitLab From ef47de91ca69c3f2c2a0aca076fa90c81d756e61 Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Fri, 13 Oct 2023 21:39:00 +0000 Subject: [PATCH 4/4] Polish the legend somewhat Smooth out the language and punctuation. --- .../merge_request_concepts/diffs/frontend.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/development/merge_request_concepts/diffs/frontend.md b/doc/development/merge_request_concepts/diffs/frontend.md index c380f480713bd1..bafd0b5e437f38 100644 --- a/doc/development/merge_request_concepts/diffs/frontend.md +++ b/doc/development/merge_request_concepts/diffs/frontend.md @@ -23,17 +23,17 @@ The Vue app for rendering diffs uses many different Vue components, some of whic with other areas of the GitLab app. The below chart shows the direction for which components get rendered. -The following legend may be useful to assist in reading the chart: +This chart contains several types of items: | Legend item | Interpretation | | ----------- | -------------- | -| `xxx~~`, `ee-xxx~~` | Indicates a shortened directory path name. Can be found in `[ee]/app/assets/javascripts`, and omits `0..n` nested folders | -| Rectangular nodes | Files | -| Oval nodes | Plain language describing a deeper concept | -| Double-rectangular nodes | Simplified code branch | -| Diamond & Circle nodes | Branches that have two (diamond) or 3+ (circle) options | -| Pendant/Banner nodes (left notch, right square) | A parent directory to shorten nested paths | -| `./` | A path relative to the closest parent directory pendant node. Non-relative paths nested under parent pendant nodes are not in that directory | +| `xxx~~`, `ee-xxx~~` | A shortened directory path name. Can be found in `[ee]/app/assets/javascripts`, and omits `0..n` nested folders. | +| Rectangular nodes | Files. | +| Oval nodes | Plain language describing a deeper concept. | +| Double-rectangular nodes | Simplified code branch. | +| Diamond and circle nodes | Branches that have 2 (diamond) or 3+ (circle) options. | +| Pendant / banner nodes (left notch, right square) | A parent directory to shorten nested paths. | +| `./` | A path relative to the closest parent directory pendant node. Non-relative paths nested under parent pendant nodes are not in that directory. | ```mermaid flowchart TB -- GitLab