- 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.
- We don't need this blanket enabled, we only have a few docs where it actually matters that there's a description, it's just cruft having to invent descriptions.
- Yes, we have yet another `.rubocop.yml` but in-line exclusions in
`<span class="display:none;">` in the Markdown seemed more ugly.
- This needed tweaks to `brew style` to make it read the new config
file when we're scanning docs.
- Blocks should open with `do` and close with `end`.
- `...` is not valid Ruby syntax, so comment it out so that the user
knows that it's a placeholder for "other things here".
- Reword the "header line details" in `Cask-Cookbook` otherwise RuboCop
crashes even with an `end` because of the empty block. There was
already an example of a valid header line in the first code block on
the page, so it's not a big loss.
In https://github.com/Homebrew/homebrew-core/pull/157910 we discussed
some improvements to docs on setting up gems. THis is an attempt at some
docs for that.
If someone can help with pip docs for this I'll add it too.
Signed-off-by: Phil Dibowitz <phil@ipom.com>
These are changes that were made in the private repository mirror
and either voted on by members already (where they were changes) or
were agreed clarifications on existing policy.
This will allow us to more easily measure test performance. The only
downside here is that we can't use it with parallel rspec because
it will show the n slowest tests for each parallel rspec run which
is not what we want.
I realized the convention in documentations is to recommend `-S`, not `-Syu`, as a system upgrade is usually an overkill. This change also makes Homebrew's documentation more consistent.
The hope is that this will be clearer and less annoying for users.
A user came to us a couple weeks ago stating that it was confusing
that the `brew upgrade` command printed an error when a pinned
formula had a new version available and didn't get upgraded.
This PR changes that message to a warning from an error. While looking
into this we found that there is another message that gets printed
when a package dependency doesn't get upgraded because it is pinned
and that got turned into a warning from a normal message. Honestly,
that should be more worrying for the user anyway; it could lead to
a program not working correctly in the worst case.
I also added a message to the `brew pin` command warning about
potential unintended behavior if a dependency gets pinned and another
package requires a newer version of it.
Lastly, I added a commented out deprecation notice for the
`brew upgrade --ignore-pinned` command since it's now the default.
Adjust various maintainer and contributor-focused documents after
recent maintainer conversations and generally anything I noticed was
wrong or outdated as I went through these.
