- `brew pin` should cover casks now that upgrades skip both package types.
- Cask pin records keep list, info and upgrade output consistent.
- `auto_updates true` casks need a warning because app updaters bypass Homebrew.
- explain when `*-full` variants fit better than expanding defaults
- distinguish `foo-full` variants from `foo@1.2` versioned formulae
- add `docs/AGENTS.md` with the working docs verification workflow
- exclude `docs/AGENTS.md` from the published docs site to keep
`rake test` focused on public documentation pages
- move the supported and unsupported guidance into
`docs/Versions.md` so users get one consistent answer when
they want to freeze formula versions
- distinguish the churn-reduction knobs from the
personal-tap workflows, including `brew pin`,
`$HOMEBREW_NO_AUTO_UPDATE`, `brew bundle --no-upgrade`,
`$HOMEBREW_BUNDLE_NO_UPGRADE`,
`$HOMEBREW_NO_INSTALL_UPGRADE`,
`$HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK`,
`brew version-install`, and `brew extract`
- explain the support boundaries that matter in practice:
missed security updates, custom tap maintenance, and only
filing issues after `brew update` when the problem
reproduces with core formulae
- point the FAQ, tips, bundle, and tap docs at the new
section so the wording stays aligned as these workflows
evolve
- 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!
As discussed at the AGM:
- Only allow formula/cask forks to be used when either blessed by
the source or used by two other major distributions,
- Further elaborate and tweak reasons to deprecate/disable formulae.
- Allow more versioned formulae when widely used.
- Add a document (based on above) for deprecating/disabling casks.
While we're here:
- let VSCode Markdown linting remove the trailing `!` from an
Acceptable Casks heading
* Removed all mentions of `homebrew/versions`, since it's dead and long gone.
* Version support requirement: Updated PHP example, and added contrasting example to address a common misconception
* Standardize on the use of "main" rather than "non-versioned" to avoid confusion
* Directly address the most common reason for (disallowed) versioning
This is used to indicate a formula is a version of another formula.
This will be used to provide a consistent interface for older formulae
versions and replaces the use of `conflicts_with`.
Patrick Linnane