From d0795d2b9d87bcd1ec0165774e27458e60dc2922 Mon Sep 17 00:00:00 2001 From: Issy Long Date: Mon, 5 Feb 2024 01:47:47 +0100 Subject: [PATCH 1/2] Delete ancient 'managing PRs' flowchart - This diagram was really old and didn't reflect the current practices (a lot more things are automated now, hurray). - Anything we replace it with will get outdated fast too. - Also delete the diagramming docs since I don't believe we have made another diagram since this one which got out of date and forgotten about since it was a DrawIO SVG and not easily editable as code. - If we want diagrams these days, we can use Mermaid which is diagrams-as-code. --- .editorconfig | 5 --- docs/Diagram-Guidelines.md | 45 ------------------- ...Homebrew-homebrew-core-Maintainer-Guide.md | 6 +-- .../docs/managing-pull-requests.drawio.svg | 1 - 4 files changed, 1 insertion(+), 56 deletions(-) delete mode 100644 docs/Diagram-Guidelines.md delete mode 100644 docs/assets/img/docs/managing-pull-requests.drawio.svg diff --git a/.editorconfig b/.editorconfig index 3c1a0b9a9f3b7..a3f724a3659a0 100644 --- a/.editorconfig +++ b/.editorconfig @@ -16,11 +16,6 @@ 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 deleted file mode 100644 index a31669784e94f..0000000000000 --- a/docs/Diagram-Guidelines.md +++ /dev/null @@ -1,45 +0,0 @@ -# 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/Homebrew-homebrew-core-Maintainer-Guide.md b/docs/Homebrew-homebrew-core-Maintainer-Guide.md index 074cc2388c52f..f68337009e799 100644 --- a/docs/Homebrew-homebrew-core-Maintainer-Guide.md +++ b/docs/Homebrew-homebrew-core-Maintainer-Guide.md @@ -25,7 +25,7 @@ For most PRs that make formula modifications, you can simply approve the PR and Certain PRs may not be merged automatically by [@BrewTestBot](https://github.com/BrewTestBot), even after they've been approved. This includes PRs with the `new formula`, `automerge-skip`, and `linux-only` labels. To trigger a merge for these PRs, run `brew pr-publish`. -PRs modifying formulae that don't need bottles or making changes that don't require new bottles to be pulled should use GitHub's squash & merge or rebase & merge workflows. See the [table below](#how-to-merge-without-bottles) for more details. +PRs modifying formulae that don't need bottles or making changes that don't require new bottles to be pulled should use GitHub's squash & merge or rebase & merge workflows. Otherwise, you should use `brew pr-pull` (or `rebase`/`cherry-pick` contributions). @@ -35,10 +35,6 @@ Cherry-picking changes the date of the commit, which kind of sucks. Don’t `merge` unclean branches. So if someone is still learning `git` and 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) - Only one maintainer is necessary to approve and merge the addition of a new or updated formula which passes CI. However, if the formula addition or update proves controversial the maintainer who adds it will be expected to answer requests and fix problems that arise with it in future. ### How to merge without bottles diff --git a/docs/assets/img/docs/managing-pull-requests.drawio.svg b/docs/assets/img/docs/managing-pull-requests.drawio.svg deleted file mode 100644 index 983cfbee627f4..0000000000000 --- a/docs/assets/img/docs/managing-pull-requests.drawio.svg +++ /dev/null @@ -1 +0,0 @@ -
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
saybottle
: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
saybottle
: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 From a8beb98bade5557e906117d4c519553cd75a3224 Mon Sep 17 00:00:00 2001 From: Issy Long Date: Mon, 5 Feb 2024 15:49:40 +0100 Subject: [PATCH 2/2] PRs raised at 2am are only half done, zzzz --- docs/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 1fba8ed3a7403..ec857f27f89dc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -51,7 +51,6 @@ - [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) - [Reproducible Builds](Reproducible-Builds.md)