Merge pull request #8627 from claui/pr-diagram

Add flowchart for managing ready-to-merge PRs

.editorconfig

@@ -16,6 +16,11 @@ trim_trailing_whitespace = true
 # trailing whitespace is crucial for patches
 trim_trailing_whitespace = false
 
+[**.drawio.svg]
+indent_size = unset
+indent_style = unset
+insert_final_newline = false
+
 [**.md]
 trim_trailing_whitespace = true
 x-soft-wrap-text = true

docs/Diagram-Guidelines.md

+# Diagram Guidelines
+
+## Preferred file format
+
+For complex diagrams, use the `.drawio.svg` format.
+
+Files with the `.drawio.svg` extension are SVG files with embedded [draw.io](https://www.diagrams.net/) source code. Using that format lends itself to a developer-friendly workflow: it is valid SVG, plays well with `git diff` and can be edited in lock-step using various online and offline flavours of draw.io. If you use VS Code, you can use an [extension](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio) for draw.io integration.
+
+Files in the `.drawio.svg` format can be processed offline.
+
+## Embedding a diagram into Markdown
+
+To embed a `.drawio.svg` file into Markdown, use the same syntax as for any image. Example: `![My diagram](my-diagram.drawio.svg)`
+
+Mind that GitHub doesn’t allow styling in Markdown documents. Where styling is allowed (e.g. in the exported brew.sh version of the documentation), always set a background colour of `white` for the diagram. That’s the colour draw.io assumes, and keeps the diagram easy to read in dark mode without further customization. You can use the CSS selector `img[src$=".drawio.svg"]` for styling.
+
+## Example
+
+Example for an SVG image embedded into Markdown:
+
+```md
+![Example diagram: Managing Pull Requests](assets/img/docs/managing-pull-requests.drawio.svg)
+```
+
+Result:
+
+![Example diagram: Managing Pull Requests](assets/img/docs/managing-pull-requests.drawio.svg)
+
+Example for styling (where allowed):
+
+```css
+img[src$=".drawio.svg"] {
+  background-color: white;
+  margin-bottom: 20px;
+  padding: 5%;
+  width: 90%;
+}
+
+@media (prefers-color-scheme: dark) {
+  img[src$=".drawio.svg"] {
+    filter: invert(85%);
+    -webkit-filter: invert(85%);
+  }
+}
+```

docs/Maintainer-Guidelines.md

@@ -76,6 +76,10 @@ their branch is filled with nonsensical merges, then `rebase` and squash
 the commits. Our main branch history should be useful to other people,
 not confusing.
 
+Here’s a flowchart for managing a PR which is ready to merge:
+
+![Flowchart for managing pull requests](assets/img/docs/managing-pull-requests.drawio.svg)
+
 ### Testing
 
 We need to at least check that it builds. Use the [Brew Test Bot](Brew-Test-Bot.md) for this.

docs/README.md

@@ -46,6 +46,7 @@
 - [Building Against Non-Homebrew Dependencies](Building-Against-Non-Homebrew-Dependencies.md)
 - [How To Create (And Maintain) A Tap](How-to-Create-and-Maintain-a-Tap.md)
 - [Brew Test Bot](Brew-Test-Bot.md)
+- [Diagram Guidelines](Diagram-Guidelines.md)
 - [Prose Style Guidelines](Prose-Style-Guidelines.md)
 - [Type Checking with Sorbet](Typechecking.md)