The Documentation workflow installs Vale unpinned, and 3.17.0 reports two
errors that 3.16.0 did not, so every pull request built after its release
fails the docs job on unchanged content. Both are real violations of our
own styles rather than new false positives.
Drop an Oxford comma in the conference reimbursement list, and link to
How-To-Open-a-Homebrew-Pull-Request.md by the name Homebrew.Terms exempts,
which is also how every other page refers to it.
- Gives the security guide a URL that targets `homebrew security`.
- Keeps the old supply chain URL working through `redirect_from`.
- Updates internal links while limiting visible text changes.
- explain recent npm and PyPI supply-side incidents and patterns
- contrast Homebrew's reviewed, checksummed, bottled trust model
- note most protections predate the current supply-chain focus
- document mitigations: sandboxing, environment filtering, cooldowns
- note maintainer vetting, inactivity removal and 2FA requirements
- state Homebrew trusts no third-party non-Homebrew repositories
- note tap migrations never move packages out to third-party taps
- note Homebrew does not defer to upstream against users' interests
- explain ephemeral build runners and building from source
- describe the cask trust model and how it compares to upstream
- note bottles are only supported for core and warn off other paths
- explain prioritising security over backwards compatibility
- note layered infrastructure cross-checks and GitHub security features
- explain why Homebrew needs no blanket or double dependency cooldown
- warn about untrusted third-party taps in the interesting taps doc
- record one-sentence-per-line and aligned-table docs Markdown style
- cross-link the new doc from index, Tap Trust and the FAQ
- explain the principles behind our AI/LLM usage rules for
maintainers and contributors rather than just the requirements
- riff off Administrate's "AI at Administrate" guidance: human in
the loop, trust appropriately, use AI to improve AI, try things
- cross-link from the index, `CONTRIBUTING` guide, pull request
template, PR how-to, maintainer guidelines and new maintainer
checklist so the guidance is discoverable where AI use comes up
- Group documentation links by audience so the index is easier to scan.
- Keep the docs index free of a redundant visible heading.
- Exempt only the docs index from first-heading markdown lint rules.
- Document the bundle install step needed before serving docs locally.
- Avoid `jekyll-remote-theme` so docs builds use local shared files.
- Reference canonical `brew.sh` theme assets instead of copying them here.
- Keep only the layouts and includes needed by the docs site.
- Point shared docs page images at `brew.sh` for HTML-Proofer.
- Render the install demo GIF at retina size in the README.
The jekyll-relative-links plugin converts .md links to clean URLs (e.g.,
`FAQ.md` to `/FAQ`), which works for all links in `index.md` except
`C++-Standard-Libraries.md`. The issue is that the plugin assumes that
the link is escaped with `CGI.escape`, and calls `CGI.unescape` to try
to reverse the escaping. The plus signs `+` are unescaped to space
characters, so the unescaped link matches nothing, and the link is left
unconverted.
Fix that by escaping the plus signs in the link, which allows the plugin
to convert the link as expected.
Fixes#22102.
- add a dedicated guide for upstream projects working with Homebrew
- link relevant maintainer and policy docs to the new guidance
- explain escalation and decision-making expectations more clearly
Combine the separate formulae, cask and code deprecation
docs into a single page with shared lifecycle overview,
per-type criteria and `redirect_from` for old URLs.
- add `docs/Deprecating-Disabling-and-Removing.md`
- add code deprecation policy (`odeprecated`/`odisabled`
lifecycle, API classification, CLI flags, env vars)
- delete old `-Formulae` and `-Casks` pages, redirect
via `redirect_from` on the new page
- update cross-references in cookbooks, maintainer guide,
`Releases.md`, `index.md` and `formula.rb`
- add missing `index.md` entries for `Homebrew-and-Java`,
`Linux-CI`
This was in the (soon to be archived) Homebrew/homebrew-bundle
repository's `README`. There's some good content here that doesn't
cleanly fit into the `brew` manpage so let's move it here.
While we're here, let's de-emphasize `whalebrew` as it's not
widely used and add commented-out deprecation warnings for its future
deprecation.
- Most of these were fine still, apart from:
- FAQ: `hub` is less maintained than `gh`.
- Brew-Maintainer-Guide: link to GitHub docs on commit signing via GPG or SSH.
- Interesting-Taps-and-Forks: remove outdated information about `homebrew/core` being in `Library/Taps`.
- New-Maintainer-Checklist: remove outdated information about the `@members` team.
- At the AGM we formed an ad-hoc documentation working group.
- One of our ideas was that we should have a last reviewed date for
documentation, so that we can periodically implement a review
mechanism (GitHub Actions posts to Slack for a regular documentation
outdatedness check?) to track how old docs are and ensure they're
still relevant.
- This is a first step towards that goal, by adding a `last_review_date`
to the metadata of all docs with a date of earlier than Homebrew's
inception because everything needs reviewing so that we start from a
good base!
Douglas Eichelberger