Merge pull request #8465 from Rylan12/license-docs

docs: update license documentation

Library/Homebrew/formula.rb

@@ -2219,12 +2219,13 @@ class Formula
     # @!attribute [w]
     # The SPDX ID of the open-source license that the formula uses.
     # Shows when running `brew info`.
-    # Use `:any`, `:all` or `:with` to describe complex license expressions.
-    # `:any` should be used when the user can choose which license to use.
-    # `:all` should be used when the user must use all licenses.
+    # Use `:any_of`, `:all_of` or `:with` to describe complex license expressions.
+    # `:any_of` should be used when the user can choose which license to use.
+    # `:all_of` should be used when the user must use all licenses.
     # `: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 license.
+    # @see https://docs.brew.sh/License-Guidelines Homebrew License Guidelines
     # @see https://spdx.github.io/spdx-spec/appendix-IV-SPDX-license-expressions/ SPDX license expression guide
     # <pre>license "BSD-2-Clause"</pre>
     # <pre>license "EPL-1.0+"</pre>
@@ -2232,6 +2233,12 @@ class Formula
     # <pre>license all_of: ["MIT", "GPL-2.0-only"]</pre>
     # <pre>license "GPL-2.0-only" => { with: "LLVM-exception" }</pre>
     # <pre>license :public_domain</pre>
+    # <pre>license any_of: [
+    #   "MIT",
+    #   :public_domain,
+    #   all_of: ["0BSD", "Zlib", "Artistic-1.0+"],
+    #   "Apache-2.0" => { with: "LLVM-exception" },
+    # ]</pre>
     def license(args = nil)
       if args.nil?
         @licenses

docs/Formula-Cookbook.md

@@ -95,13 +95,9 @@ We only accept formulae that use a [Debian Free Software Guidelines license](htt
 
 Use the license 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.
 
-If the software is available under multiple licenses, you should list them all in an array:
+Use `:any_of`, `:all_of` or `:with` to describe complex license expressions. `:any_of` should be used when the user can choose which license to use. `:all_of` should be used when the user must use all licenses. `: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 license.
 
-```ruby
-license ["MIT", "GPL-2.0"]
-```
-
-Note: only specify multiple licenses if the formula gives the user a choice between the licenses. Formulae that have different licenses for different parts of their software should specify only the more restrictive license. For help determining which license is more restrictive, take a look [https://choosealicense.com](https://choosealicense.com/licenses/) or the [Comparison of free and open-source software licences Wikipedia page](https://en.wikipedia.org/wiki/Comparison_of_free_and_open-source_software_licences).
+Check out the [License Guidelines](License-Guidelines.md) for examples of complex license expressions in Homebrew formulae.
 
 ### Check the build system
 

docs/License-Guidelines.md

@@ -0,0 +1,110 @@
+# License Guidelines
+
+We only accept formulae that use a [Debian Free Software Guidelines license](https://wiki.debian.org/DFSGLicenses) or are released into the public domain following [DFSG Guidelines on Public Domain software](https://wiki.debian.org/DFSGLicenses#Public_Domain).
+
+## Specifying a License
+
+All licenses are identified by their license identifier from the [SPDX License List](https://spdx.org/licenses/).
+
+Specify a license by passing it to the `license` method:
+
+```ruby
+license "MIT"
+```
+
+The public domain can be indicated using a symbol:
+
+```ruby
+license :public_domain
+```
+
+## Complex SPDX License Expressions
+
+Some formulae have multiple licenses that need to be combined in different ways. In these cases, a more complex license expression can be used. These expressions are based on the [SPDX License Expression Guidelines](https://spdx.github.io/spdx-spec/appendix-IV-SPDX-license-expressions/).
+
+Add a `+` to indicate that the user can choose a later version of the same license:
+
+```ruby
+license "EPL-1.0+"
+```
+
+GNU licenses (`GPL`, `LGPL`, `AGPL` and `GFDL`) require either the `-only` or the `-or-later` suffix to indicate whether a later version of the license is allowed:
+
+```ruby
+license "LGPL-2.1-only"
+```
+
+```ruby
+license "GPL-1.0-or-later"
+```
+
+Use `:any_of` to indicate that the user can choose which license applies:
+
+```ruby
+license any_of: ["MIT", "0BSD"]
+```
+
+Use `:all_of` to indicate that the user must comply with multiple licenses:
+
+```ruby
+license all_of: ["MIT", "0BSD"]
+```
+
+Use `:with` to indicate a license exception:
+
+```ruby
+license "MIT" => { with: "LLVM-exception" }
+```
+
+These expressions can be nested as needed:
+
+```ruby
+license any_of: [
+  "MIT",
+  :public_domain,
+  all_of: ["0BSD", "Zlib", "Artistic-1.0+"],
+  "Apache-2.0" => { with: "LLVM-exception" },
+]
+```
+
+## Specifying Forbidden Licenses
+
+The `HOMEBREW_FORBIDDEN_LICENSES` environment variable can be set to forbid installation of formulae that require or have dependencies that require certain licenses.
+
+The `HOMEBREW_FORBIDDEN_LICENSES` should be set to a space separated list of licenses. Use `public_domain` to forbid installation of formulae with a `:public_domain` license.
+
+For example, the following forbids installation of `MIT`, `Artistic-1.0` and `:public_domain` licenses:
+
+```bash
+export HOMEBREW_FORBIDDEN_LICENSES="MIT Artistic-1.0 public_domain"
+```
+
+In this example Homebrew would refuse to install any formula that specifies the `MIT` license. Homebrew would also forbid installation of any formula that declares a dependency on a formula that specifies `MIT`, even if the original formula has an allowed license.
+
+Homebrew interprets complex license expressions and determines whether the licenses allow installation. To continue the above example, Homebrew would not allow installation of a formula with the following license declarations:
+
+```ruby
+license any_of: ["MIT", "Artistic-1.0"]
+```
+
+```ruby
+license all_of: ["MIT", "0BSD"]
+```
+
+Homebrew _would_ allow formulae with the following declaration to be installed:
+
+```ruby
+license any_of: ["MIT", "0BSD"]
+```
+
+`HOMEBREW_FORBIDDEN_LICENSES` can also forbid future versions of specific licenses. For example, to forbid `Artistic-1.0`, `Artistic-2.0` and any future Artistic licenses, use:
+
+```bash
+export HOMEBREW_FORBIDDEN_LICENSES="Artistic-1.0+"
+```
+
+For GNU licenses (such as `GPL`, `LGPL`, `AGPL` and `GFDL`), use `-only` or `-or-later`. For example, the following would forbid `GPL-2.0`, `LGPL-2.1` and `LGPL-3.0` formulae from being installed, but would allow `GPL-3.0`
+
+```bash
+export HOMEBREW_FORBIDDEN_LICENSES="GPL-2.0-only LGPL-2.1-or-later"
+```

docs/README.md

@@ -37,6 +37,7 @@
 - [How To Open A Pull Request (and get it merged)](How-To-Open-a-Homebrew-Pull-Request.md)
 - [Formula Cookbook](Formula-Cookbook.md)
 - [Acceptable Formulae](Acceptable-Formulae.md)
+- [License Guidelines](License-Guidelines.md)
 - [Formulae Versions](Versions.md)
 - [Node for Formula Authors](Node-for-Formula-Authors.md)
 - [Python for Formula Authors](Python-for-Formula-Authors.md)