Docs: improve deprecation doc

[iMichka]

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.

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same change?
• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your changes? Here's an example.
• Have you successfully run brew style with your changes locally?
• Have you successfully run brew typecheck with your changes locally?
• Have you successfully run brew tests with your changes locally?

---

[iMichka]

I made the diagram with draw.io, and I can provide the original file (even add it to git or share it on Slack) if someone wants to play with it.
It's a draft (I did not invest too much time in it): I'm waiting on feedback before improving the design.

Let me know if this is an idea that is worth pursuing.

We improved the doc after the AGM by tweaking the rules, but I think we made it way more complex to understand than before. I think a picture is way better than all the text we have right now.

[MikeMcQuaid]

Sorry, strongly oppose making this a SVG/PNG diagram.

These SVG/PNG diagrams bitrot super quickly and don't get updated (as we saw with the Brew Test Bot flowchart recently).

If we want it to be a diagram: it should be something like Mermaid that can be edited/searched/linted as text: https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

[reitermarkus]

What is the difference between “Does not have an open source license” and “the project has no license”? The latter implies the former, no?

I tried to convert it to 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

[p-linnane]

What is the difference between “Does not have an open source license” and “the project has no license”? The latter implies the former, no?

A project may be relicensed to something like BUSL or Elastic, which are not open source licenses, but they are still licensed.

[reitermarkus]

A project may be relicensed to something like BUSL or Elastic, which are not open source licenses, but they are still licensed.

Yes, but “no license” still implies “no open source license”, right? So either way would be straight to removal.

[bevanjkay]

If the license changes we can continue using the previous bottles that were shipped under the open-source license, and we go down the deprecate lifecycle.
If an existing formula is found to have no license/an unsuitable license (on the tag that the bottles were built from) then it would be disabled immediately.

[reitermarkus]

So, this?

flowchart TD
  A(Does it have an open-source licence?) -->|no| B
  B(Does it have a previous version with an open-source licence?)
  B -->|no| C(Disable.)
  B -->|yes| D(Deprecate.)

Do we even have formulae that do not currently have an open source license and also didn't previously?

[p-linnane]

Yes, but “no license” still implies “no open source license”, right? So either way would be straight to removal.

It can. Currently taking "no license" to mean that the formulae literally has no license at all. We've been slowly working on correcting that over the last few months though and have been removing things that do not have a discoverable license.

[p-linnane]

Do we even have formulae that do not currently have an open source license and also didn't previously?

We can deprecate if the license changes to something not open source. If we have no license in a formula, and can't find one, it should be outright removed immediately.

[iMichka]

Good idea to use mermaid for this. I'm going to update it with the latest comments.

This doc will end up on https://docs.brew.sh, do we have mermaid integration there?

[MikeMcQuaid]

This doc will end up on docs.brew.sh, do we have mermaid integration there?

Not by default, it seems, looks like it needs some extra work to get it rendering.

[reitermarkus]

There is jekyll-spaceship which supports rendering Mermaid. I'm using this for my personal website:

jekyll-spaceship:
  mermaid-processor:
    mode: pre-fetch

[EricFromCanada]

That isn't in the list of supported plugins for GitHub Pages, so including it would require some additional effort.

[github-actions]

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.

[iMichka]

I'm on it, trying to get jekyll-spaceship working locally first.