From c18980d20dc9d3c3b29abb472eda1a5a3eb155da Mon Sep 17 00:00:00 2001 From: Issy Long Date: Thu, 31 Aug 2023 15:25:59 +0100 Subject: [PATCH 01/11] Run the docs site's broken link checker in the docs linting CI job - We had `rake test` as a task, but we never actually ran it in CI or anywhere before building the site. - The `html-proofer` gem [only supports Ruby 3.1](https://github.com/gjtorikian/html-proofer/blob/main/html-proofer.gemspec#L20), so I bumped the linting job to use Ruby 3.1 across the board. - This will make things slower (or maybe it's taking ages because of my dodgy hotel internet connection), maybe we should only run it on a schedule as a separate job? - Fixes https://github.com/Homebrew/brew/issues/ 15908. --- .github/workflows/docs.yml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index f666307ba6..9fc10f3883 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -32,7 +32,7 @@ jobs: - name: Install Ruby uses: ruby/setup-ruby@v1 with: - ruby-version: "2.7" + ruby-version: "3.1" bundler-cache: true working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}/docs @@ -40,9 +40,11 @@ jobs: working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}/docs run: bundle exec rake lint - - name: Build docs site + - name: Check for broken links, then build docs site working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}/docs - run: bundle exec rake build + run: | + bundle exec rake test + bundle exec rake build rubydoc: if: github.repository == 'Homebrew/brew' From 7f2ed15db37518d4cbc68649039fd003384d00c6 Mon Sep 17 00:00:00 2001 From: Issy Long Date: Thu, 31 Aug 2023 16:02:18 +0100 Subject: [PATCH 02/11] Update `html-proofer` configuration - the parameter names changed --- docs/Rakefile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/Rakefile b/docs/Rakefile index e28c12460d..487015a302 100644 --- a/docs/Rakefile +++ b/docs/Rakefile @@ -19,17 +19,17 @@ task test: :build do "./_site", parallel: { in_threads: 4 }, favicon: true, - http_status_ignore: [0, 403], + ignore_status_codes: [0, 403], assume_extension: true, check_favicon: true, check_opengraph: true, check_html: true, check_img_http: true, enforce_https: true, - file_ignore: [ + ignore_files: [ %r{Kickstarter-Supporters}, ], - url_ignore: [ + ignore_urls: [ "http://formulae.brew.sh", %r{https://github.com/Homebrew/brew/edit/gh-pages//}, ] From 7f3a4fe66713cd54e30034bbb4f69c86334ebac4 Mon Sep 17 00:00:00 2001 From: Issy Long Date: Thu, 31 Aug 2023 16:15:23 +0100 Subject: [PATCH 03/11] Fix link to Ruby's `FileUtils` documentation in the Formula Cookbook --- docs/Formula-Cookbook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index a449872225..f58fdb2a0c 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -793,7 +793,7 @@ Note that in the context of Homebrew, [`libexec`](https://rubydoc.brew.sh/Formul ### File-level operations -You can use the file utilities provided by Ruby's [`FileUtils`](https://www.ruby-doc.org/stdlib/libdoc/fileutils/rdoc/index.html). These are included in the [`Formula`](https://rubydoc.brew.sh/Formula) class, so you do not need the `FileUtils.` prefix to use them. +You can use the file utilities provided by Ruby's [`FileUtils`](https://ruby-doc.org/stdlib-2.7.0/libdoc/fileutils/rdoc/FileUtils.html). These are included in the [`Formula`](https://rubydoc.brew.sh/Formula) class, so you do not need the `FileUtils.` prefix to use them. When creating symlinks, take special care to ensure they are *relative* symlinks. This makes it easier to create a relocatable bottle. For example, to create a symlink in `bin` to an executable in `libexec`, use: From 32bbe6d5de7e49ab0efecdbdbd9aeb6e479c493a Mon Sep 17 00:00:00 2001 From: Issy Long Date: Thu, 31 Aug 2023 16:27:56 +0100 Subject: [PATCH 04/11] Ignore `1 For 32-bit or PPC support see [Tigerbrew](https://github.com/mistydemeo/tigerbrew). +1 For 32-bit or PPC support see [Tigerbrew](https://github.com/mistydemeo/tigerbrew). -2 macOS 11 (Big Sur) or higher is best and supported, 10.11 (El Capitan) – 10.15 (Catalina) are unsupported but may work and 10.10 (Yosemite) and older will not run Homebrew at all. For 10.4 (Tiger) – 10.6 (Snow Leopard) see [Tigerbrew](https://github.com/mistydemeo/tigerbrew). +2 macOS 11 (Big Sur) or higher is best and supported, 10.11 (El Capitan) – 10.15 (Catalina) are unsupported but may work and 10.10 (Yosemite) and older will not run Homebrew at all. For 10.4 (Tiger) – 10.6 (Snow Leopard) see [Tigerbrew](https://github.com/mistydemeo/tigerbrew). -3 You may need to install Xcode, the CLT, or both depending on the formula, to install a bottle (binary package) which is the only supported configuration. Downloading Xcode may require an Apple Developer account on older versions of Mac OS X. Sign up for free at [Apple's website](https://developer.apple.com/account/). +3 You may need to install Xcode, the CLT, or both depending on the formula, to install a bottle (binary package) which is the only supported configuration. Downloading Xcode may require an Apple Developer account on older versions of Mac OS X. Sign up for free at [Apple's website](https://developer.apple.com/account/). -4 The one-liner installation method found on [brew.sh](https://brew.sh) uses the Bourne-again shell at `/bin/bash`. Notably, `zsh`, `fish`, `tcsh` and `csh` will not work. +4 The one-liner installation method found on [brew.sh](https://brew.sh) uses the Bourne-again shell at `/bin/bash`. Notably, `zsh`, `fish`, `tcsh` and `csh` will not work. From 3c69671b84112e55ea4eecd6f7be4cf6d6b853bd Mon Sep 17 00:00:00 2001 From: Issy Long Date: Thu, 31 Aug 2023 16:57:25 +0100 Subject: [PATCH 05/11] The `py2cairo` formula was deleted, don't refer to it in docs anymore --- docs/Python-for-Formula-Authors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Python-for-Formula-Authors.md b/docs/Python-for-Formula-Authors.md index 353f981f02..3ba246a394 100644 --- a/docs/Python-for-Formula-Authors.md +++ b/docs/Python-for-Formula-Authors.md @@ -4,7 +4,7 @@ This document explains how to successfully use Python in a Homebrew formula. Homebrew draws a distinction between Python **applications** and Python **libraries**. The difference is that users generally do not care that applications are written in Python; it is unusual that a user would expect to be able to `import foo` after installing an application. Examples of applications are [`ansible`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/a/ansible.rb) and [`jrnl`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/j/jrnl.rb). -Python libraries exist to be imported by other Python modules; they are often dependencies of Python applications. They are usually no more than incidentally useful in a terminal. Examples of libraries are [`py2cairo`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/p/py2cairo.rb) and the bindings that are installed by [`protobuf`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/p/protobuf.rb). +Python libraries exist to be imported by other Python modules; they are often dependencies of Python applications. They are usually no more than incidentally useful in a terminal. An example of a library is the bindings that are installed by [`protobuf`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/p/protobuf.rb). Bindings are a special case of libraries that allow Python code to interact with a library or application implemented in another language. From c0144234d163f4582cae5e2ba3be4ebebfefe94f Mon Sep 17 00:00:00 2001 From: Issy Long Date: Fri, 1 Sep 2023 00:44:20 +0100 Subject: [PATCH 06/11] The E&R policy doc is only in `Homebrew/homebrew-governance-private` --- docs/How-To-Organize-AGM.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/How-To-Organize-AGM.md b/docs/How-To-Organize-AGM.md index cca2a77fbe..a59ba15925 100644 --- a/docs/How-To-Organize-AGM.md +++ b/docs/How-To-Organize-AGM.md @@ -144,7 +144,8 @@ source of funding before seeking Homebrew funding. PLC, TSC, PL and maintainers can expect to have all reasonable, in-policy expenses covered while members will be considered on a case-by-case basis. -See also the [Reimbursement Policy](Expense-and-Reimbursement-Policy.md#travel) for process and details on what is covered. +Read the Expense and Reimbursement policy document in `Homebrew/homebrew-governance-private`. +It contains the process and details on what is covered. It is important that all attendees expecting reimbursement stay in-policy. ## Ideas for future AGMs From 17de29e93d3a06616a966261f55653251ab5610b Mon Sep 17 00:00:00 2001 From: Issy Long Date: Fri, 1 Sep 2023 00:45:42 +0100 Subject: [PATCH 07/11] Disable HTMLProofer's `assume_extension` option - It reports a lot of broken internal links that do actually exist, it's just file extension inference weirdness. --- docs/Rakefile | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/Rakefile b/docs/Rakefile index 487015a302..bbb8bd3a12 100644 --- a/docs/Rakefile +++ b/docs/Rakefile @@ -20,7 +20,6 @@ task test: :build do parallel: { in_threads: 4 }, favicon: true, ignore_status_codes: [0, 403], - assume_extension: true, check_favicon: true, check_opengraph: true, check_html: true, From 484c7e07d1415cdfa4ef1f785d75790ec5ff1a2c Mon Sep 17 00:00:00 2001 From: Issy Long Date: Fri, 1 Sep 2023 00:46:10 +0100 Subject: [PATCH 08/11] Cache the external links for an hour, and ignore GitHub.com --- docs/Rakefile | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/Rakefile b/docs/Rakefile index bbb8bd3a12..b0b6a9a5e4 100644 --- a/docs/Rakefile +++ b/docs/Rakefile @@ -29,8 +29,13 @@ task test: :build do %r{Kickstarter-Supporters}, ], ignore_urls: [ - "http://formulae.brew.sh", - %r{https://github.com/Homebrew/brew/edit/gh-pages//}, - ] + %r{https://formulae.brew.sh"}, + %r{https://github.com/} + ], + cache: { + timeframe: { + external: "1h" + } + } ).run end From ee7ff978770f0f7bce89b73381fb0b6153e3ed7f Mon Sep 17 00:00:00 2001 From: Issy Long Date: Fri, 1 Sep 2023 00:48:18 +0100 Subject: [PATCH 09/11] Fix link to renamed Cask Cookbook section --- docs/Adding-Software-to-Homebrew.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Adding-Software-to-Homebrew.md b/docs/Adding-Software-to-Homebrew.md index b097019e18..26418349ed 100644 --- a/docs/Adding-Software-to-Homebrew.md +++ b/docs/Adding-Software-to-Homebrew.md @@ -86,7 +86,7 @@ cask "noisy" do end ``` -Here is a last example for `airdisplay`, which uses a `pkg` installer to install the application instead of a stand-alone application bundle (`.app`). Note the [`uninstall pkgutil` stanza](Cask-Cookbook.md#uninstall-key-pkgutil), which is needed to uninstall all files that were installed using the installer. +Here is a last example for `airdisplay`, which uses a `pkg` installer to install the application instead of a stand-alone application bundle (`.app`). Note the [`uninstall pkgutil` stanza](Cask-Cookbook.md#uninstall-pkgutil), which is needed to uninstall all files that were installed using the installer. You will also see how to adapt `version` to the download `url`. Use [our custom `version` methods](Cask-Cookbook.md#version-methods) to do so, resorting to the standard [Ruby String methods](https://ruby-doc.org/core/String.html) when they don’t suffice. From 1c91da27bbb9446e388e7deb7cff153bc0da3818 Mon Sep 17 00:00:00 2001 From: Issy Long Date: Fri, 1 Sep 2023 01:00:15 +0100 Subject: [PATCH 10/11] The Python Setuptools docs have moved around too, the reference no longer exists --- docs/Python-for-Formula-Authors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Python-for-Formula-Authors.md b/docs/Python-for-Formula-Authors.md index 3ba246a394..23a62fa544 100644 --- a/docs/Python-for-Formula-Authors.md +++ b/docs/Python-for-Formula-Authors.md @@ -189,7 +189,7 @@ where `prefix` is the destination prefix (usually `libexec` or `prefix`). ### What is `--single-version-externally-managed`? -`--single-version-externally-managed` ("SVEM") is a Setuptools-only [argument to `setup.py install`](https://setuptools.readthedocs.io/en/latest/setuptools.html?#install-run-easy-install-or-old-style-installation). The primary effect of SVEM is using Distutils to perform the install instead of Setuptools' `easy_install`. +`--single-version-externally-managed` ("SVEM") is a [Setuptools](https://setuptools.readthedocs.io/en/latest/setuptools.html)-only argument to `setup.py install`. The primary effect of SVEM is using Distutils to perform the install instead of Setuptools' `easy_install`. `easy_install` does a few things that we need to avoid: From 210b678cafe8b1ae4d6639d688a120db957c2dcc Mon Sep 17 00:00:00 2001 From: Issy Long Date: Fri, 1 Sep 2023 01:03:26 +0100 Subject: [PATCH 11/11] The `test` task already runs `build`, so no need for it twice --- .github/workflows/docs.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 9fc10f3883..fe0baadde7 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -40,11 +40,10 @@ jobs: working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}/docs run: bundle exec rake lint - - name: Check for broken links, then build docs site + - name: Build the site and check for broken links working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}/docs run: | bundle exec rake test - bundle exec rake build rubydoc: if: github.repository == 'Homebrew/brew'