diff --git a/docs/Acceptable-Casks.md b/docs/Acceptable-Casks.md index d4e418b939..1386395984 100644 --- a/docs/Acceptable-Casks.md +++ b/docs/Acceptable-Casks.md @@ -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 diff --git a/docs/Acceptable-Formulae.md b/docs/Acceptable-Formulae.md index 75ec264ca3..921b3fe067 100644 --- a/docs/Acceptable-Formulae.md +++ b/docs/Acceptable-Formulae.md @@ -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 diff --git a/docs/Expense-and-Reimbursement-Policy.md b/docs/Expense-and-Reimbursement-Policy.md index 1beb10b9ba..788aaa3808 100644 --- a/docs/Expense-and-Reimbursement-Policy.md +++ b/docs/Expense-and-Reimbursement-Policy.md @@ -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. diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index c7112edd1b..b3e5a995ba 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -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: diff --git a/docs/Homebrew-Governance.md b/docs/Homebrew-Governance.md index c8f1241fd7..515fbaf5ff 100644 --- a/docs/Homebrew-Governance.md +++ b/docs/Homebrew-Governance.md @@ -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. diff --git a/docs/Homebrew-homebrew-core-Maintainer-Guide.md b/docs/Homebrew-homebrew-core-Maintainer-Guide.md index 9c8be33dbc..6b8a880c9d 100644 --- a/docs/Homebrew-homebrew-core-Maintainer-Guide.md +++ b/docs/Homebrew-homebrew-core-Maintainer-Guide.md @@ -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 diff --git a/docs/How-to-Build-Software-Outside-Homebrew-with-Homebrew-keg-only-Dependencies.md b/docs/How-to-Build-Software-Outside-Homebrew-with-Homebrew-keg-only-Dependencies.md index 97ac09ac93..2268d61968 100644 --- a/docs/How-to-Build-Software-Outside-Homebrew-with-Homebrew-keg-only-Dependencies.md +++ b/docs/How-to-Build-Software-Outside-Homebrew-with-Homebrew-keg-only-Dependencies.md @@ -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 diff --git a/docs/Language-Runtimes-and-Packages.md b/docs/Language-Runtimes-and-Packages.md index 379f1a1bd1..c23ba1999c 100644 --- a/docs/Language-Runtimes-and-Packages.md +++ b/docs/Language-Runtimes-and-Packages.md @@ -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 diff --git a/docs/Language-Specific-Formulae.md b/docs/Language-Specific-Formulae.md index 5605b86831..beada4c784 100644 --- a/docs/Language-Specific-Formulae.md +++ b/docs/Language-Specific-Formulae.md @@ -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 diff --git a/docs/Package-Acceptance-Policy.md b/docs/Package-Acceptance-Policy.md index 23d936e47b..34dee2d988 100644 --- a/docs/Package-Acceptance-Policy.md +++ b/docs/Package-Acceptance-Policy.md @@ -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.