mirror of
https://github.com/Homebrew/brew.git
synced 2026-08-12 22:29:27 +04:00
docs: implementlists for readability
This commit is contained in:
Bevan Kay
+16
-15
@@ -28,11 +28,11 @@ The [Cask Cookbook](Cask-Cookbook.md#casks-pinned-to-specific-versions) document
|
||||
|
||||
### Platform compatibility and macOS security protections
|
||||
|
||||
A cask may support macOS, Linux or both when Homebrew supports its artifact types on those operating systems.
|
||||
A cask is not required to support both operating systems.
|
||||
A cask must work on every operating system and architecture it declares.
|
||||
A cask that supports macOS must work on the latest major version of macOS.
|
||||
On macOS, it must not require System Integrity Protection or Gatekeeper to be disabled or bypassed.
|
||||
* A cask may support macOS, Linux or both when Homebrew supports its artifact types on those operating systems.
|
||||
* A cask is not required to support both operating systems.
|
||||
* A cask must work on every operating system and architecture it declares.
|
||||
* A cask that supports macOS must work on the latest major version of macOS.
|
||||
* On macOS, it must not require System Integrity Protection or Gatekeeper to be disabled or bypassed.
|
||||
|
||||
Apple's [Rosetta 2 transition documentation](https://developer.apple.com/documentation/apple-silicon/about-the-rosetta-translation-environment/) says general application support will remain available through macOS 27, with only a narrower legacy-games-focused subset beyond that.
|
||||
Casks that require [`requires_rosetta`](Cask-Cookbook.md#caveats-mini-dsl) remain eligible while the latest major macOS release provides that general support.
|
||||
@@ -45,10 +45,10 @@ Language and regional editions of the same application should normally be repres
|
||||
|
||||
### Trials and optional paid features
|
||||
|
||||
A time-limited trial is eligible only when the same download can be activated as the full version without being downloaded again.
|
||||
The trial cask is not eligible when the full version is available only through the Mac App Store.
|
||||
A free version that works indefinitely with optional paid features is eligible.
|
||||
An obsolete direct-download build is not eligible when the developer distributes the current version exclusively through the Mac App Store.
|
||||
* A time-limited trial is eligible only when the same download can be activated as the full version without being downloaded again.
|
||||
* The trial cask is not eligible when the full version is available only through the Mac App Store.
|
||||
* A free version that works indefinitely with optional paid features is eligible.
|
||||
* An obsolete direct-download build is not eligible when the developer distributes the current version exclusively through the Mac App Store.
|
||||
|
||||
### Appropriate package type
|
||||
|
||||
@@ -60,9 +60,9 @@ The [Adding Software to Homebrew](Adding-Software-to-Homebrew.md#choose-a-packag
|
||||
|
||||
### Verifiable upstream distribution
|
||||
|
||||
A cask must use a download published by the developer or by a distribution source the developer publicly endorses.
|
||||
An unendorsed third-party build, a binary available only through a forum or similar posting or a download hidden behind account registration on a host unrelated to the homepage is not eligible.
|
||||
An installer package that requires certificate verification to be disabled is not eligible.
|
||||
* A cask must use a download published by the developer or by a distribution source the developer publicly endorses.
|
||||
* An unendorsed third-party build, a binary available only through a forum or similar posting or a download hidden behind account registration on a host unrelated to the homepage is not eligible.
|
||||
* An installer package that requires certificate verification to be disabled is not eligible.
|
||||
|
||||
### Forks and apps with conflicting names
|
||||
|
||||
@@ -77,9 +77,10 @@ A duplicate cask for the same software, release and channel is not eligible.
|
||||
|
||||
### Notability exceptions
|
||||
|
||||
The [shared notability metrics](Package-Acceptance-Policy.md#notability) may not represent the notability of an established application when the repository is used only to host its binaries.
|
||||
A cask backed by an established maintainer or prolific contributor may also receive further consideration because it has a clearer maintenance path.
|
||||
A recently released application may receive further consideration when there is substantial, independently verifiable public interest and multiple requests for inclusion.
|
||||
* The [shared notability metrics](Package-Acceptance-Policy.md#notability) may not represent the notability of an established application when the repository is used only to host its binaries.
|
||||
* A cask backed by an established maintainer or prolific contributor may also receive further consideration because it has a clearer maintenance path.
|
||||
* A recently released application may receive further consideration when there is substantial, independently verifiable public interest and multiple requests for inclusion.
|
||||
|
||||
These circumstances permit further review but do not guarantee inclusion.
|
||||
|
||||
## Security and malware
|
||||
|
||||
+13
-14
@@ -47,17 +47,16 @@ An install step must not resolve a moving or otherwise unreproducible dependency
|
||||
|
||||
### Source availability and licences
|
||||
|
||||
A formula in `homebrew/core` must be open source under a licence compatible with the [Debian Free Software Guidelines](https://wiki.debian.org/DFSGLicenses).
|
||||
It must either build from source or install portable, platform-independent output such as Java bytecode.
|
||||
|
||||
Proprietary or platform-specific binary-only software belongs in a cask.
|
||||
A core formula must not depend on a cask, proprietary software or a runtime step that automatically installs either one.
|
||||
* A formula in `homebrew/core` must be open source under a licence compatible with the [Debian Free Software Guidelines](https://wiki.debian.org/DFSGLicenses).
|
||||
* It must either build from source or install portable, platform-independent output such as Java bytecode.
|
||||
* Proprietary or platform-specific binary-only software belongs in a cask.
|
||||
* A core formula must not depend on a cask, proprietary software or a runtime step that automatically installs either one.
|
||||
|
||||
### Stable releases
|
||||
|
||||
Upstream must identify the packaged version as stable and provide an immutable tag or release.
|
||||
Release archives are preferred to Git checkouts and should include the version in the filename when upstream provides that form.
|
||||
A new formula must build without downstream-only patches on its supported platforms.
|
||||
* Upstream must identify the packaged version as stable and provide an immutable tag or release.
|
||||
* Release archives are preferred to Git checkouts and should include the version in the filename when upstream provides that form.
|
||||
* A new formula must build without downstream-only patches on its supported platforms.
|
||||
|
||||
Software without a stable release is difficult to reproduce, bottle and support and is not eligible for `homebrew/core`.
|
||||
|
||||
@@ -68,9 +67,9 @@ A supported application bundle published by upstream belongs in [`homebrew/cask`
|
||||
|
||||
### Optional graphical interfaces
|
||||
|
||||
When upstream can build both a command-line or library component and an optional graphical interface, the command-line or library component should remain the formula's primary purpose.
|
||||
A widely used native graphical interface may be included when it does not impose a disproportionate dependency cost.
|
||||
An X11 or XQuartz interface should not be enabled by default as it provides a poor macOS experience.
|
||||
* When upstream can build both a command-line or library component and an optional graphical interface, the command-line or library component should remain the formula's primary purpose.
|
||||
* A widely used native graphical interface may be included when it does not impose a disproportionate dependency cost.
|
||||
* An X11 or XQuartz interface should not be enabled by default as it provides a poor macOS experience.
|
||||
|
||||
### Dependencies and full variants
|
||||
|
||||
@@ -94,9 +93,9 @@ Software that requires extensive manual pre-installation or post-installation st
|
||||
|
||||
### Shared and static libraries
|
||||
|
||||
Shared libraries are preferred when upstream can provide either shared or static libraries.
|
||||
A formula may install both when static libraries have a demonstrated use.
|
||||
Static-only libraries are not appropriate when other formulae depend on them because every dependent must be rebuilt after an update.
|
||||
* Shared libraries are preferred when upstream can provide either shared or static libraries.
|
||||
* A formula may install both when static libraries have a demonstrated use.
|
||||
* Static-only libraries are not appropriate when other formulae depend on them because every dependent must be rebuilt after an update.
|
||||
|
||||
### Vendored dependencies
|
||||
|
||||
|
||||
@@ -49,9 +49,9 @@ Maintainers are not expected to advance significant personal funds.
|
||||
Submit an approved expense through [Homebrew on Open Collective](https://opencollective.com/homebrew/expenses/new) promptly after paying it.
|
||||
Follow Open Source Collective's current [invoice and reimbursement guidance](https://docs.oscollective.org/for-hosted-member-projects/spending-money-and-getting-paid/invoice-and-reimbursement-examples).
|
||||
|
||||
Use a reimbursement for a project purchase that you have already paid.
|
||||
Use an invoice for completed work or services.
|
||||
If an expense contains multiple receipts, enter them as separate line items.
|
||||
* Use a reimbursement for a project purchase that you have already paid.
|
||||
* Use an invoice for completed work or services.
|
||||
* If an expense contains multiple receipts, enter them as separate line items.
|
||||
|
||||
Open Source Collective will request payment, identity or tax information before it can pay an expense.
|
||||
|
||||
|
||||
@@ -88,7 +88,13 @@ We only accept formulae that use a licence compatible with the [Debian Free Soft
|
||||
|
||||
Use the licence identifier from the [SPDX License List](https://spdx.org/licenses/) e.g. `license "BSD-2-Clause"`, or use `license :public_domain` for public domain software.
|
||||
|
||||
Use `:any_of`, `:all_of` or `:with` to describe complex licence expressions. `:any_of` should be used when the user can choose which licence to use. `:all_of` should be used when the user must use all licences. `:with` should be used to specify a valid SPDX exception. Add `+` to an identifier to indicate that the formulae can be licensed under later versions of the same licence.
|
||||
Use `:any_of`, `:all_of` or `:with` to describe complex licence expressions.
|
||||
|
||||
* `:any_of` should be used when the user can choose which licence to use.
|
||||
* `:all_of` should be used when the user must use all licences.
|
||||
* `:with` should be used to specify a valid SPDX exception.
|
||||
|
||||
Add `+` to an identifier to indicate that the formulae can be licensed under later versions of the same licence.
|
||||
|
||||
Check out the [Licence Guidelines](Licence-Guidelines.md) for examples of complex licence expressions in Homebrew formulae.
|
||||
|
||||
@@ -150,7 +156,12 @@ A `String` (e.g. `"jpeg"`) specifies a formula dependency.
|
||||
|
||||
A `Symbol` (e.g. `:xcode`) specifies a [`Requirement`](/rubydoc/Requirement.html) to restrict installation to systems meeting certain criteria, which can be fulfilled by one or more formulae, casks or other system-wide installed software (e.g. Xcode). Some [`Requirement`](/rubydoc/Requirement.html)s can also take a string or symbol specifying their minimum version that the formula depends on.
|
||||
|
||||
Top-level `depends_on :macos` marks a formula as macOS-only. Top-level `depends_on macos: :sonoma` marks a formula as macOS-only and declares the minimum compatible macOS release. Top-level `depends_on maximum_macos: :ventura` marks a formula as macOS-only and declares the newest compatible macOS release. Top-level `depends_on :linux` marks a formula as Linux-only. For a formula that supports both macOS and Linux but needs a specific macOS version, put the macOS version requirement inside `on_macos`.
|
||||
* Top-level `depends_on :macos` marks a formula as macOS-only.
|
||||
* Top-level `depends_on macos: :sonoma` marks a formula as macOS-only and declares the minimum compatible macOS release.
|
||||
* Top-level `depends_on maximum_macos: :ventura` marks a formula as macOS-only and declares the newest compatible macOS release.
|
||||
* Top-level `depends_on :linux` marks a formula as Linux-only.
|
||||
|
||||
For a formula that supports both macOS and Linux but needs a specific macOS version, put the macOS version requirement inside `on_macos`.
|
||||
|
||||
A `Hash` (e.g. `=>`) adds information to a dependency. Given a string or symbol, the value can be one or more of the following values:
|
||||
|
||||
|
||||
@@ -134,9 +134,9 @@ No single person holds special authority beyond the Project Leader role.
|
||||
|
||||
## 3. Decision-making
|
||||
|
||||
Formal governance decisions are made by vote of all Maintainers.
|
||||
Major financial decisions (i.e. changes to existing documented financial processes or new one-time expenditures) are made by vote of the Lead Maintainers.
|
||||
Minor financial approvals (i.e. approving expected Open Collective expenses) can be made by any Lead Maintainer.
|
||||
- Formal governance decisions are made by vote of all Maintainers.
|
||||
- Major financial decisions (i.e. changes to existing documented financial processes or new one-time expenditures) are made by vote of the Lead Maintainers.
|
||||
- Minor financial approvals (i.e. approving expected Open Collective expenses) can be made by any Lead Maintainer.
|
||||
|
||||
- Informal decisions may proceed by discussion unless a vote is requested by any Lead Maintainer.
|
||||
- Formal votes require a simple majority.
|
||||
|
||||
@@ -79,18 +79,18 @@ We now accept versioned formulae as long as they [meet the requirements](Version
|
||||
Every formula change must at least build successfully in the required BrewTestBot jobs.
|
||||
Use [BrewTestBot](BrewTestBot.md) for this validation.
|
||||
|
||||
Verify installed functionality rather than relying solely on the contributor's local result.
|
||||
Require a meaningful `test do` block that exercises the installed software without network access.
|
||||
For a library, compile and run a small program against the installed headers and library when practical.
|
||||
If the reviewer cannot evaluate specialised behaviour, request reproducible validation from upstream documentation, an existing test suite or another reviewer with relevant knowledge.
|
||||
- Verify installed functionality rather than relying solely on the contributor's local result.
|
||||
- Require a meaningful `test do` block that exercises the installed software without network access.
|
||||
- For a library, compile and run a small program against the installed headers and library when practical.
|
||||
- If the reviewer cannot evaluate specialised behaviour, request reproducible validation from upstream documentation, an existing test suite or another reviewer with relevant knowledge.
|
||||
|
||||
If a formula uses a source-code repository, its `url` must identify an immutable tag or revision.
|
||||
Do not package a moving branch as a stable release.
|
||||
|
||||
Do not merge a formula update with a failing `brew test`.
|
||||
Fix the failure or replace a flaky test with a reliable test that still detects whether the installed software works.
|
||||
If the failure comes from Homebrew or CI, fix that problem or add a narrowly scoped formula workaround before merging.
|
||||
Do not normalise merging a red pull request.
|
||||
- Do not merge a formula update with a failing `brew test`.
|
||||
- Fix the failure or replace a flaky test with a reliable test that still detects whether the installed software works.
|
||||
- If the failure comes from Homebrew or CI, fix that problem or add a narrowly scoped formula workaround before merging.
|
||||
- Do not normalise merging a red pull request.
|
||||
|
||||
## Retagged formulae
|
||||
|
||||
|
||||
@@ -8,9 +8,9 @@ A keg-only formula is installed in its own prefix but is not linked into Homebre
|
||||
This prevents a Homebrew package from shadowing software provided by macOS or conflicting with another formula.
|
||||
See the [FAQ explanation of keg-only formulae](FAQ.md#what-does-keg-only-mean).
|
||||
|
||||
Do not replace macOS tools or libraries with manual symlinks.
|
||||
Avoid `brew link --force` because it makes unrelated builds and system commands resolve a different dependency globally.
|
||||
Pass the required location only to the build that needs it.
|
||||
- Do not replace macOS tools or libraries with manual symlinks.
|
||||
- Avoid `brew link --force` because it makes unrelated builds and system commands resolve a different dependency globally.
|
||||
- Pass the required location only to the build that needs it.
|
||||
|
||||
## Discover the prefix
|
||||
|
||||
|
||||
@@ -11,9 +11,9 @@ redirect_from:
|
||||
Homebrew provides language runtimes and applications but does not manage packages installed directly by tools such as `gem`, `npm`, `pip` or `cpan`.
|
||||
Those packages are outside Homebrew's installation records and are not upgraded or removed by `brew`.
|
||||
|
||||
Use `brew install` when Homebrew provides the runtime or application you need.
|
||||
Use each language's project environment and lock file for project dependencies.
|
||||
Avoid running language package managers with `sudo` or changing ownership of system-managed directories to make an installation succeed.
|
||||
- Use `brew install` when Homebrew provides the runtime or application you need.
|
||||
- Use each language's project environment and lock file for project dependencies.
|
||||
- Avoid running language package managers with `sudo` or changing ownership of system-managed directories to make an installation succeed.
|
||||
|
||||
## Python
|
||||
|
||||
|
||||
@@ -107,10 +107,11 @@ Use upstream build-system options to direct bindings into the formula prefix rat
|
||||
### Build-system integration for Python bindings
|
||||
|
||||
When more than one Python is available in the dependency graph, pass the declared interpreter to the build system explicitly.
|
||||
For CMake, use the variable recognised by upstream's discovery module, commonly `Python3_EXECUTABLE`, `Python_EXECUTABLE` or the older `PYTHON_EXECUTABLE`.
|
||||
For Meson, check how upstream calls `find_installation()` and use its supported options to select the interpreter.
|
||||
If Meson cannot infer Homebrew's installation directories, set `python.purelibdir` or `python.platlibdir` to a path inside the formula prefix.
|
||||
For Autotools projects, use an upstream `--with-python` option when available or disable the build-system installation and install the bindings with the declared interpreter and `std_pip_args`.
|
||||
|
||||
- For CMake, use the variable recognised by upstream's discovery module, commonly `Python3_EXECUTABLE`, `Python_EXECUTABLE` or the older `PYTHON_EXECUTABLE`.
|
||||
- For Meson, check how upstream calls `find_installation()` and use its supported options to select the interpreter.
|
||||
- If Meson cannot infer Homebrew's installation directories, set `python.purelibdir` or `python.platlibdir` to a path inside the formula prefix.
|
||||
- For Autotools projects, use an upstream `--with-python` option when available or disable the build-system installation and install the bindings with the declared interpreter and `std_pip_args`.
|
||||
|
||||
## Node.js
|
||||
|
||||
|
||||
@@ -26,8 +26,11 @@ Discontinued software and software that relies on Homebrew-specific patches to c
|
||||
## Notability
|
||||
|
||||
A new package must demonstrate public interest beyond its author.
|
||||
A GitHub project normally satisfies this requirement when it has at least 30 forks, 30 watchers or 75 stars.
|
||||
For a self-submission by the repository owner, the corresponding thresholds are 90 forks, 90 watchers or 225 stars.
|
||||
A GitHub project normally satisfies this requirement by meeting one of these thresholds:
|
||||
|
||||
* at least 30 forks, 30 watchers or 75 stars, or
|
||||
* at least 90 forks, 90 watchers or 225 stars for a self-submission by the repository owner.
|
||||
|
||||
Equivalent public evidence may be considered for software hosted elsewhere.
|
||||
The metrics apply to the canonical upstream repository, not an unendorsed mirror or code-hosting fork.
|
||||
A code repository less than 30 days old is normally not eligible.
|
||||
|
||||
Reference in New Issue
Block a user