diff --git a/.editorconfig b/.editorconfig index a3f724a365..3c1a0b9a9f 100644 --- a/.editorconfig +++ b/.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 diff --git a/docs/Diagram-Guidelines.md b/docs/Diagram-Guidelines.md new file mode 100644 index 0000000000..a31669784e --- /dev/null +++ b/docs/Diagram-Guidelines.md @@ -0,0 +1,45 @@ +# 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%); + } +} +``` diff --git a/docs/Maintainer-Guidelines.md b/docs/Maintainer-Guidelines.md index 7eebe79bb8..fd5a61b862 100644 --- a/docs/Maintainer-Guidelines.md +++ b/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. diff --git a/docs/README.md b/docs/README.md index f665a8fc16..eb7d7b73c5 100644 --- a/docs/README.md +++ b/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) diff --git a/docs/assets/img/docs/managing-pull-requests.drawio.svg b/docs/assets/img/docs/managing-pull-requests.drawio.svg new file mode 100644 index 0000000000..66197c84d4 --- /dev/null +++ b/docs/assets/img/docs/managing-pull-requests.drawio.svg @@ -0,0 +1,783 @@ + + + + + + + + + + +
+
+
+ Yes +
+
+
+ + + Yes + + + + + + + + +
+
+
+ No, it’s +
+ fine +
+
+
+ + + No, it’s... + + + + + + + +
+
+
+ Want to +
+ modify or +
+ rebase? +
+
+
+ + + Want to... + + + + + + + + + +
+
+
+

+ hub checkout +

+
+
+
+ + + hub checkout + + + + + + + +
+
+
+ Modify and push +
+ to PR branch +
+
+
+ + + Modify and push... + + + + + + + + + +
+
+
+ Pull request on +
+ homebrew-core +
+
+
+ + + Pull request on... + + + + + + + + +
+
+
+ No, +
+ it needs +
+ bottles +
+
+
+ + + No,... + + + + + + + + +
+
+
+ Yes +
+
+
+ + + Yes + + + + + + + +
+
+
+ Does it +
+ say  + + bottle +
+ :unneeded + +
+ ? +
+
+
+ + + Does it... + + + + + + + + +
+
+
+ Yes +
+
+
+ + + Yes + + + + + + + + +
+
+
+ No/not yet +
+ but I want +
+ to override +
+
+
+ + + No/not yet... + + + + + + + +
+
+
+ CI passed? +
+
+
+ + + CI passed? + + + + + + + + +
+
+
+ Yes +
+
+
+ + + Yes + + + + + + + + +
+
+
+ No +
+
+
+ + + No + + + + + + + +
+
+
+ Version or +
+ revision +
+ bump? +
+
+
+ + + Version or... + + + + + + + + +
+
+
+ No, it’s +
+ a new +
+ formula +
+
+
+ + + No, it’s... + + + + + + + + +
+
+
+ Yes +
+
+
+ + + Yes + + + + + + + +
+
+
+ Existing +
+ formula? +
+
+
+ + + Existing... + + + + + + + + +
+
+
+ Yes +
+
+
+ + + Yes + + + + + + + + +
+
+
+ No, +
+ it’s +
+ urgent +
+
+
+ + + No,... + + + + + + + +
+
+
+ Can it wait? +
+
+
+ + + Can it wait? + + + + + + + +
+
+
+
+ Approve ✅ PR and wait  + + for BrewTestBot + +
+
+ + to merge + +
+
+
+
+ + + Approve ✅ PR and... + + + + + + + +
+
+
+

+ brew +
+ pr-publish +

+
+
+
+ + + brew... + + + + + + + +
+
+
+ Push the +
+ “Rebase and merge” button +
+
+
+ + + Push the... + + + + + + + + +
+
+
+ Yes +
+
+
+ + + Yes + + + + + + + + +
+
+
+ No/ +
+ don’t +
+ care +
+
+
+ + + No/... + + + + + + + +
+
+
+ Prefer to +
+ run CI after- +
+ wards? +
+
+
+ + + Prefer to... + + + + + + + + +
+
+
+ Yes +
+
+
+ + + Yes + + + + + + + +
+
+
+ Does it +
+ say  + + bottle +
+ :unneeded + +
+ ? +
+
+
+ + + Does it... + + + + + + + + +
+
+
+ No, +
+ it needs +
+ bottles +
+
+
+ + + No,... + + + + + + + + +
+
+
+ Yes +
+
+
+ + + Yes + + + + + + + +
+
+
+ Rebuild +
+ bottles after- +
+ wards? +
+
+
+ + + Rebuild... + + + + + + + + +
+
+
+ No, they’re +
+ not affected +
+
+
+ + + No, they’re... + + + + + + + + +
+
+
+ Yes +
+
+
+ + + Yes + + + + + + + + +
+
+
+ No, merge +
+ immediately +
+
+
+ + + No, merge... + + + + + + + +
+
+
+ Want to +
+ push to the PR +
+ branch? +
+
+
+ + + Want to... + + + + + + + + + +
+
+
+

+ brew pr-pull +

+
+
+
+ + + brew pr-pull + + + + + + + +
+
+
+ Modify and push +
+ to master +
+
+
+ + + Modify and push... + + + + + + + + + Viewer does not support full SVG 1.1 + + + + \ No newline at end of file