From f4d81fee1c57b0e152876ea8bb57115807b3c223 Mon Sep 17 00:00:00 2001 From: Claudia Date: Sun, 6 Sep 2020 00:35:26 +0200 Subject: [PATCH 1/2] Add flowchart for managing pull requests - Add flowchart for handling ready-to-merge pull requests - Add diagram guidelines Many thanks to Sean Molenaar for the idea and initial version of the chart. CC: Sean Molenaar --- .editorconfig | 5 + docs/Diagram-Guidelines.md | 45 ++ docs/Maintainer-Guidelines.md | 4 + docs/README.md | 1 + .../docs/managing-pull-requests.drawio.svg | 498 ++++++++++++++++++ 5 files changed, 553 insertions(+) create mode 100644 docs/Diagram-Guidelines.md create mode 100644 docs/assets/img/docs/managing-pull-requests.drawio.svg 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..7267ef9f65 --- /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..508802d73c --- /dev/null +++ b/docs/assets/img/docs/managing-pull-requests.drawio.svg @@ -0,0 +1,498 @@ + + + + + + + + + + +
+
+
+ Yes +
+
+
+ + + Yes + + + + + + + + +
+
+
+ No, it’s +
+ fine +
+
+
+ + + No, it’s... + + + + + + + +
+
+
+ Want to +
+ modify or +
+ rebase? +
+
+
+ + + Want to... + + + + + + + + + +
+
+
+

+ brew pr-pull +

+
+
+
+ + + brew pr-pull + + + + + + + +
+
+
+ Modify and push +
+
+
+ + + 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 + + + + + + +
+
+
+ Yes +
+
+
+ + + Yes + + + + + + + + +
+
+
+ No, it’s +
+ urgent +
+
+
+ + + No, it’s... + + + + + + + +
+
+
+ Can it wait? +
+
+
+ + + Can it wait? + + + + + + + +
+
+
+ Accept and wait for test-bot +
+
+
+ + + Accept and wait... + + + + + + + +
+
+
+

+ brew +
+ pr-publish +

+
+
+
+ + + brew... + + + + + + + +
+
+
+ Push the button +
+
+
+ + + Push the button + + + + + + + + + Viewer does not support full SVG 1.1 + + + + \ No newline at end of file From 4bb396bca978f5776c273f614e3f93188a846b32 Mon Sep 17 00:00:00 2001 From: Claudia Date: Mon, 7 Sep 2020 23:49:21 +0200 Subject: [PATCH 2/2] Apply suggested changes to diagram and guidelines --- docs/Diagram-Guidelines.md | 4 +- .../docs/managing-pull-requests.drawio.svg | 499 ++++++++++++++---- 2 files changed, 394 insertions(+), 109 deletions(-) diff --git a/docs/Diagram-Guidelines.md b/docs/Diagram-Guidelines.md index 7267ef9f65..a31669784e 100644 --- a/docs/Diagram-Guidelines.md +++ b/docs/Diagram-Guidelines.md @@ -4,7 +4,7 @@ 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 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. @@ -12,7 +12,7 @@ Files in the `.drawio.svg` format can be processed offline. 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. +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 diff --git a/docs/assets/img/docs/managing-pull-requests.drawio.svg b/docs/assets/img/docs/managing-pull-requests.drawio.svg index 508802d73c..66197c84d4 100644 --- a/docs/assets/img/docs/managing-pull-requests.drawio.svg +++ b/docs/assets/img/docs/managing-pull-requests.drawio.svg @@ -1,14 +1,14 @@ - + - + - - + + -
+
Yes @@ -16,17 +16,17 @@
- + Yes - - + + -
+
No, it’s @@ -36,7 +36,7 @@
- + No, it’s... @@ -62,41 +62,43 @@ - - - + + + -
+

- brew pr-pull + hub checkout

- - brew pr-pull + + hub checkout - + -
+
Modify and push +
+ to PR branch
- - Modify and push + + Modify and push... @@ -121,12 +123,12 @@ - - + + -
+
No, @@ -138,17 +140,17 @@
- + No,... - - + + -
+
Yes @@ -156,16 +158,16 @@
- + Yes - + -
+
Does it @@ -182,17 +184,17 @@
- + Does it... - - + + -
+
Yes @@ -200,17 +202,17 @@
- + Yes - - + + -
+
No/not yet @@ -222,16 +224,16 @@
- + No/not yet... - + -
+
CI passed? @@ -239,17 +241,17 @@
- + CI passed? - - + + -
+
Yes @@ -257,17 +259,17 @@
- + Yes - - + + -
+
No @@ -275,16 +277,16 @@
- + No - + -
+
Version or @@ -296,17 +298,17 @@
- + Version or... - - + + -
+
No, it’s @@ -318,17 +320,17 @@
- + No, it’s... - - + + -
+
Yes @@ -336,16 +338,16 @@
- + Yes - + -
+
Existing @@ -355,17 +357,17 @@
- + Existing... - - + + -
+
Yes @@ -373,52 +375,38 @@
- + Yes + + -
+
- Yes -
-
-
- - - Yes - - - - - - - - -
-
-
- No, it’s + No, +
+ it’s
urgent
- - No, it’s... + + No,... - + -
+
Can it wait? @@ -426,33 +414,43 @@
- + Can it wait? - + -
+
- Accept and wait for test-bot +
+ Approve ✅ PR and wait  + + for BrewTestBot + +
+
+ + to merge + +
- - Accept and wait... + + Approve ✅ PR and... - + -
+

@@ -464,25 +462,312 @@

- + brew... - + -
+
- Push the button + Push the +
+ “Rebase and merge” button
- - Push the 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...