Docs: improve deprecation doc

The current documentation:
- contains a lot of text
- is sometimes unclear (or at least you need to re-read it carefully multiple times)

Using a diagram feels more appropriate.

docs/Deprecating-Disabling-and-Removing-Formulae.md

@@ -10,6 +10,53 @@ These general rules of thumb can be followed:
 - `disable!` should be used for formulae that _cannot_ be used.
 - Formulae that are no longer acceptable in `homebrew/core` or have been disabled for over a year _should_ be removed.
 
+## Flow
+
+```mermaid!
+flowchart TD
+    DEPRECATE(Deprecate.)
+    DISABLE(Disable.)
+    REMOVE(Remove.)
+
+    LICENSE(Does is have an open source licence?)
+    LICENSE -->|no| REMOVE
+
+    ACCEPTABLE(Does it meet our acceptable formula criteria?)
+    ACCEPTABLE -->|no| REMOVE
+
+    VERSIONED[Is it versioned?]
+    VERSIONED -->|yes| REMOVE
+
+    HAS_DEPENDENTS(Does is have any dependent?)
+    HAS_DEPENDENTS -->|no| MORE_THAN_1000
+
+    MORE_THAN_1000(Does is have more than 1000 downloads in 90 days?)
+    MORE_THAN_1000 ---|no| DISABLED_3
+
+    DISABLED_3(Is is disabled for at least 3 months?)
+    DISABLED_3 -->|yes| REMOVE
+    DISABLED_3 -->|no| ZERO_INSTALLS
+
+
+    ZERO_INSTALLS(Does it have zero installs in the last 90 days?)
+    ZERO_INSTALLS -->|yes| DISABLE
+
+    MORE_THAN_1000 ---|yes| DEPRECATED_6
+
+    DEPRECATED_6(Is is deprecated for at least six months?)
+    DEPRECATED_6 -->|yes| DISABLE
+    DEPRECATED_6 -->|no| DEPRECATED_6_NO(( ))
+
+    BUILDS(Does it build on all supported platforms?)
+    DEPRECATED_6_NO --> BUILDS -->|no| DEPRECATE
+
+    CVES(Does it have outstanding CVEs?)
+    DEPRECATED_6_NO --> CVES -->|yes| DEPRECATE
+
+    DISCONTINUED(Is it discontinued upstream?)
+    DEPRECATED_6_NO --> DISCONTINUED -->|yes| DEPRECATE
+```
+
 ## Deprecation
 
 If a user attempts to install a deprecated formula, they will be shown a warning message but the install will proceed.
@@ -18,13 +65,6 @@ A formula should be deprecated to indicate to users that the formula should not
 
 The most common reasons for deprecation are when the upstream project is deprecated, unmaintained, or archived.
 
-Formulae should only be deprecated if at least one of the following are true:
-
-- the formula does not build on any of our supported macOS versions and on Linux
-- the formula has outstanding CVEs
-- the formula has [zero installs in the last 90 days](https://formulae.brew.sh/analytics/install/90d/)
-- the software installed by the formula has been discontinued or abandoned upstream
-
 Formulae with dependents should not be deprecated until or when all dependents are also deprecated.
 
 To deprecate a formula, add a `deprecate!` call. This call should include a deprecation date (in the ISO 8601 format) and a deprecation reason:
@@ -43,17 +83,6 @@ If a user attempts to install a disabled formula, they will be shown an error me
 
 A formula should be disabled to indicate to users that the formula cannot be used and will be removed in the future. Disabled formulae may no longer build from source or have working bottles.
 
-The most common reasons for disabling a formula are:
-
-- it cannot be built from source on all supported OS versions (meaning no new bottles can be built)
-- it has been deprecated for a long time
-- the project has no license
-
-Popular formulae (e.g. have more than 1000 [analytics installs in the last 90 days](https://formulae.brew.sh/analytics/install/90d/)) should not be disabled without a deprecation period of at least six months even if e.g. they do not build from source and do not have a license.
-
-Unpopular formulae (e.g. have fewer than 1000 [analytics installs in the last 90 days](https://formulae.brew.sh/analytics/install/90d/)) can be disabled immediately for any of the reasons above e.g. they cannot be built from source on any supported macOS version or Linux.
-They can be manually removed three months after their disable date.
-
 To disable a formula, add a `disable!` call. This call should include a deprecation date in the ISO 8601 format and a deprecation reason:
 
 ```ruby
@@ -68,7 +97,9 @@ The `because` parameter can be a preset reason (using a symbol) or a custom reas
 
 A formula should be removed if it does not meet our criteria for [acceptable formulae](Acceptable-Formulae.md) or [versioned formulae](Versions.md), has a non-open-source license, or has been disabled for over a year.
 
-**Note: disabled formulae in `homebrew/core` will be automatically removed one year after their disable date.**
+## Deprecation - Disabling - Removal flow
+
+![Flow](assets/img/docs/deprecation.svg)
 
 ## Deprecate and Disable Reasons
 

docs/Gemfile

@@ -1,9 +1,14 @@
 source "https://rubygems.org"
 
-gem "github-pages", group: :jekyll_plugins
+group :jekyll_plugins do
+  gem "github-pages"
+  gem "jekyll-spaceship", "~> 0.5.3"
+end
 
 group :test do
   gem "html-proofer"
   gem "mdl"
   gem "rake"
 end
+
+gem "webrick", "~> 1.8"

docs/_config.yml

@@ -15,6 +15,7 @@ plugins:
   - jekyll-remote-theme
   - jekyll-seo-tag
   - jekyll-sitemap
+  - jekyll-spaceship
 
 permalink: :title
 
@@ -40,3 +41,16 @@ twitter:
 
 facebook:
   publisher: https://www.facebook.com/machomebrew/
+
+jekyll-spaceship:
+  processors:
+    - mermaid-processor
+  mermaid-processor:
+    mode: default  # mode value 'pre-fetch' for fetching image at building stage
+    css:
+      class: mermaid
+    syntax:
+      code: 'mermaid!'
+      custom: ['@startmermaid', '@endmermaid']
+    config:
+      theme: default