diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000000..64ba312816 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,67 @@ +name: Documentation CI + +on: + push: + branches: + - master + pull_request: + +permissions: + contents: read + +jobs: + linting: + if: github.repository == 'Homebrew/brew' + runs-on: ubuntu-22.04 + defaults: + run: + working-directory: docs + steps: + - name: Set up Homebrew + id: set-up-homebrew + uses: Homebrew/actions/setup-homebrew@master + + - name: Install vale + run: brew install vale + + - name: Run vale for docs linting + run: vale . + + - name: Install Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: "2.7" + bundler-cache: true + working-directory: docs + + - name: Check Markdown syntax + run: bundle exec rake lint + + - name: Build docs site + run: bundle exec rake build + + rubydoc: + if: github.repository == 'Homebrew/brew' + runs-on: ubuntu-22.04 + env: + BUNDLE_GEMFILE: ${{ github.workspace }}/rubydoc/Gemfile + steps: + - name: Set up Homebrew + id: set-up-homebrew + uses: Homebrew/actions/setup-homebrew@master + + - name: Checkout Homebrew/rubydoc.brew.sh + uses: actions/checkout@main + with: + repository: Homebrew/rubydoc.brew.sh + path: rubydoc + + - name: Install Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: "2.7" + bundler-cache: true + + - name: Process rubydoc comments + working-directory: Library/Homebrew + run: bundle exec yard doc --plugin sorbet --no-output #--fail-on-warning diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 631848e3bb..cc3797d593 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -37,18 +37,13 @@ jobs: - name: Install Bundler RubyGems run: brew install-bundler-gems --groups=sorbet - - name: Install shellcheck - run: brew install shellcheck + - name: Install shellcheck and shfmt + run: brew install shellcheck shfmt - run: brew style --display-cop-names - run: brew typecheck - - name: Run vale for docs linting - run: | - brew install vale - vale docs/ - tap-syntax: name: tap syntax needs: syntax @@ -282,6 +277,7 @@ jobs: test-default-formula-linux: name: ${{ matrix.name }} + if: startsWith(github.repository, 'Homebrew/') runs-on: ${{ matrix.runs-on }} env: HOMEBREW_BOOTSNAP: 1 diff --git a/docs/.mdl_style.rb b/docs/.mdl_style.rb index 3466dc4ffd..d7a297fede 100644 --- a/docs/.mdl_style.rb +++ b/docs/.mdl_style.rb @@ -1,4 +1,5 @@ all +rule 'MD007', indent: 2 # Unordered list indentation rule 'MD026', punctuation: ',;:' # Trailing punctuation in header exclude_rule 'MD013' # Line length exclude_rule 'MD029' # Ordered list item prefix diff --git a/docs/Adding-Software-to-Homebrew.md b/docs/Adding-Software-to-Homebrew.md index 3f1322d23f..1c20531e7c 100644 --- a/docs/Adding-Software-to-Homebrew.md +++ b/docs/Adding-Software-to-Homebrew.md @@ -178,7 +178,7 @@ Other commonly used stanzas are: | ------------------ | ----------- | | `livecheck` | Ruby block describing how to find updates for this cask (see [`livecheck` Stanza Details](Cask-Cookbook.md#stanza-livecheck)) | `pkg` | relative path to a `.pkg` file containing the distribution (see [`pkg` Stanza Details](Cask-Cookbook.md#stanza-pkg)) -| `caveats` | a string or Ruby block providing the user with cask-specific information at install time (see [`caveats` Stanza Details](Cask-Cookbook.md#stanza-caveats)) +| `caveats` | string or Ruby block providing the user with cask-specific information at install time (see [`caveats` Stanza Details](Cask-Cookbook.md#stanza-caveats)) | `uninstall` | procedures to uninstall a cask; optional unless the `pkg` stanza is used (see [`uninstall` Stanza Details](Cask-Cookbook.md#stanza-uninstall)) | `zap` | additional procedures for a more complete uninstall, including configuration files and shared resources (see [`zap` Stanza Details](Cask-Cookbook.md#stanza-zap)) diff --git a/docs/Brew-Test-Bot.md b/docs/Brew-Test-Bot.md index e42e89892f..28d32ced95 100644 --- a/docs/Brew-Test-Bot.md +++ b/docs/Brew-Test-Bot.md @@ -32,4 +32,3 @@ A passed build looks like this: --- On failed or passed builds you can click the "Details" link to view the result in GitHub Actions. - diff --git a/docs/Common-Issues-for-Core-Contributors.md b/docs/Common-Issues-for-Core-Contributors.md index c7d8dba25c..5ef376ffcc 100644 --- a/docs/Common-Issues-for-Core-Contributors.md +++ b/docs/Common-Issues-for-Core-Contributors.md @@ -9,10 +9,12 @@ This is a page for maintainers to diagnose certain build errors. ### Bottle publishes failed but the commits are correct in the git history Follow these steps to fix this issue: + * Download and extract the bottle artifact. * `brew pr-upload --no-commit` in the bottle directory. Alternative instructions using `pr-pull`: + * `git reset --hard ` in homebrew/core to reset to the commit before before all the commits created by `brew pr-pull`. * `brew pr-pull ` to upload the right bottles. Add the `--warn-on-upload-failure` flag if the bottles have been partially uploaded and you're certain that the bottle checksums will match the checksums already present in the `bottle do` block of the formula. * `git reset --hard origin/master` to return to the latest commit and discard the commits made by `brew pr-pull`. @@ -21,5 +23,4 @@ Alternative instructions using `pr-pull`: The exact atom may be different. -This can be caused by passing the obsolete `-s` flag to the linker and can be -fixed like [this](https://github.com/Homebrew/homebrew-core/commit/c4ad981d788b21a406a6efe7748f2922986919a8). +This can be caused by passing the obsolete `-s` flag to the linker and can be fixed like [this](https://github.com/Homebrew/homebrew-core/commit/c4ad981d788b21a406a6efe7748f2922986919a8). diff --git a/docs/Deprecating-Disabling-and-Removing-Formulae.md b/docs/Deprecating-Disabling-and-Removing-Formulae.md index 8ce61a93a9..240cc72c63 100644 --- a/docs/Deprecating-Disabling-and-Removing-Formulae.md +++ b/docs/Deprecating-Disabling-and-Removing-Formulae.md @@ -49,7 +49,7 @@ The most common reasons for disabling a formula are: Formulae should not be disabled without a deprecation period of at least three months unless the circumstances are exceptional (e.g. the formula does not build on any supported macOS version or Linux). Popular formulae should have longer deprecation periods. The popularity of a formula should be based on our analytics data. -**Note: disabled formulae in `homebrew/core` will be automatically removed one year after their disable date**. +**Note: disabled formulae in `homebrew/core` will be automatically removed one year after their disable date.** To disable a formula, add a `disable!` call. This call should include a deprecation date (in the ISO 8601 format) and a deprecation reason: diff --git a/docs/Homebrew-Governance-Archives.md b/docs/Homebrew-Governance-Archives.md index ccf040b826..28441bc959 100644 --- a/docs/Homebrew-Governance-Archives.md +++ b/docs/Homebrew-Governance-Archives.md @@ -1,7 +1,8 @@ # Homebrew Governance Archives {% assign governance_pages = site.pages | where: "category", "governance-archives" %} +{% assign marker = "-" %} {% for item in governance_pages -%} -- [{{ item.title }}]({{ item.url }}) +{{ marker }} [{{ item.title }}]({{ item.url }}) {% endfor %} diff --git a/docs/Homebrew-Leadership-Responsibilities.md b/docs/Homebrew-Leadership-Responsibilities.md index 2dd0ea405a..d4a1dc6af6 100644 --- a/docs/Homebrew-Leadership-Responsibilities.md +++ b/docs/Homebrew-Leadership-Responsibilities.md @@ -21,7 +21,7 @@ - January: check membership, announce AGM votes - Ask for nominations for the for the PLC and project leader, and ask who is interested in serving on the TSC - - Create ballots for the elections on https://www.opavote.com + - Create ballots for the elections on - Ask the project leader and representatives of the PLC and TSC to prepare reports for the AGM - Ask for members interested in presenting lightning talks at the AGM - February: organise the annual general meeting (AGM) @@ -29,8 +29,8 @@ - Book a group dinner (which Homebrew pays for) and check for any dietary requirements - Ask someone to bring a conference/table microphone for people to be able to remotely participate in AGM - February after the AGM: - - Add the minutes of the AGM to https://github.com/Homebrew/homebrew-governance - - Create [issue in homebrew-governance](https://github.com/homebrew/homebrew-governance/issues) to ask members who did not vote in the election whether they wish to remain or step down as members + - Add the minutes of the AGM to + - Create [issue in Homebrew/brew](https://github.com/Homebrew/brew/issues?q=is%3Aissue+in%3Atitle+membership+) to ask members who did not vote in the election whether they wish to remain or step down as members - Members that are not maintainers should be a least one of: - An current or previously active maintainer, PLC/TSC member or Project Leader - A long-standing member of the Homebrew community (e.g. been submitting good bug reports for over two years) diff --git a/docs/Homebrew-and-Python.md b/docs/Homebrew-and-Python.md index da920d8688..5eb7bd7fe4 100644 --- a/docs/Homebrew-and-Python.md +++ b/docs/Homebrew-and-Python.md @@ -87,10 +87,9 @@ CFLAGS="-I$(brew --prefix)/include" LDFLAGS="-L$(brew --prefix)/lib" pip install ## Virtualenv -**Warning!** When you `brew install` formulae that provide Python bindings, you should **not be in an active virtual environment**. +**Warning!** When you `brew install` formulae that provide Python bindings, you should **not be in an active virtual environment.** -Activate the virtualenv *after* you've brewed, or brew in a fresh terminal window. -This will ensure Python modules are installed into Homebrew's `site-packages` and *not* into that of the virtual environment. +Activate the virtualenv *after* you've brewed, or brew in a fresh terminal window. This will ensure Python modules are installed into Homebrew's `site-packages` and *not* into that of the virtual environment. Virtualenv has a `--system-site-packages` switch to allow "global" (i.e. Homebrew's) `site-packages` to be accessible from within the virtualenv. diff --git a/docs/Homebrew-homebrew-core-Maintainer-Guide.md b/docs/Homebrew-homebrew-core-Maintainer-Guide.md index dfe27fdd80..cb2a77484e 100644 --- a/docs/Homebrew-homebrew-core-Maintainer-Guide.md +++ b/docs/Homebrew-homebrew-core-Maintainer-Guide.md @@ -13,8 +13,7 @@ A detailed checklist can be found [below](#detailed-merge-checklist). This is al [pip](https://pip.pypa.io/en/stable/). - Ensure that any dependencies are accurate and minimal. We don't need to support every possible optional feature for the software. -- When bottles aren't required or affected, use the GitHub squash & merge workflow for a single-formula PR or rebase & merge workflow for a multiple-formulae PR. See the ["How to merge without bottles" section below](#how-to-merge-without-bottles) -for more details. +- When bottles aren't required or affected, use the GitHub squash & merge workflow for a single-formula PR or rebase & merge workflow for a multiple-formulae PR. See the ["How to merge without bottles" section below](#how-to-merge-without-bottles) for more details. - Use `brew pr-publish` or `brew pr-pull` otherwise, which adds messages to auto-close pull requests and pull bottles built by the Brew Test Bot. - Thank people for contributing. @@ -155,18 +154,18 @@ transparency for contributors in addition to the - bottle block is not removed Suggested reply: - ``` - Please keep bottle block in place, [@BrewTestBot](https://github.com/BrewTestBot) takes care of it. - ``` + + Please keep bottle block in place; [@BrewTestBot](https://github.com/BrewTestBot) takes care of it. + - is there a test block for other than checking version or printing help? Consider asking to add one - if CI failed - due to test block - paste relevant lines and add `test failure` label - due to build errors - paste relevant lines and add `build failure` label - due to other formulae needing revision bumps - suggest to use the following command: - ``` - # in this example PR is for `libuv` formula and `urbit` needs revision bump - brew bump-revision --message 'for libuv' urbit - ``` + + # in this example: PR is for `libuv` formula and `urbit` needs revision bump + brew bump-revision --message 'for libuv' urbit + - make sure it is one commit per revision bump - if CI is green and... - bottles need to be pulled, and... @@ -187,16 +186,14 @@ This error might pop up when parameters passed to `gcc` are in the wrong order. An example from `libmagic` formula: -``` -==> brew test libmagic --verbose -Testing libmagic -==> /usr/bin/gcc -I/home/linuxbrew/.linuxbrew/Cellar/libmagic/5.38/include -L/home/linuxbrew/.linuxbrew/Cellar/libmagic/5.38/lib -lmagic test.c -o test -/tmp/ccNeDVRt.o: In function `main': -test.c:(.text+0x15): undefined reference to `magic_open' -test.c:(.text+0x4a): undefined reference to `magic_load' -test.c:(.text+0x81): undefined reference to `magic_file' -collect2: error: ld returned 1 exit status -``` + ==> brew test libmagic --verbose + Testing libmagic + ==> /usr/bin/gcc -I/home/linuxbrew/.linuxbrew/Cellar/libmagic/5.38/include -L/home/linuxbrew/.linuxbrew/Cellar/libmagic/5.38/lib -lmagic test.c -o test + /tmp/ccNeDVRt.o: In function `main': + test.c:(.text+0x15): undefined reference to `magic_open' + test.c:(.text+0x4a): undefined reference to `magic_load' + test.c:(.text+0x81): undefined reference to `magic_file' + collect2: error: ld returned 1 exit status Solution: diff --git a/docs/Maintainers-Avoiding-Burnout.md b/docs/Maintainers-Avoiding-Burnout.md index 9a55338e5d..5ac9d8d5db 100644 --- a/docs/Maintainers-Avoiding-Burnout.md +++ b/docs/Maintainers-Avoiding-Burnout.md @@ -46,4 +46,4 @@ work to be done. --- -_Thanks to https://gist.github.com/ryanflorence/124070e7c4b3839d4573 which influenced this document_ +_Thanks to which influenced this document._ diff --git a/docs/Rakefile b/docs/Rakefile index 042dfa64d1..e28c12460d 100644 --- a/docs/Rakefile +++ b/docs/Rakefile @@ -8,8 +8,8 @@ task :build do end desc "Run Markdownlint to validate the Markdown style." -task lint: :build do - sh "mdl", "." +task :lint do + sh "mdl $(git ls-files '*.md' | grep -v 'Manpage.md')" end desc "Run HTMLProofer to validate the HTML output." diff --git a/docs/governance/2021-agm-minutes.md b/docs/governance/2021-agm-minutes.md index ac7bafefd8..8e3ea8b38e 100644 --- a/docs/governance/2021-agm-minutes.md +++ b/docs/governance/2021-agm-minutes.md @@ -31,7 +31,6 @@ Jonathan Chang and Issy Long are elected. - - 11:57–12:00 Election of the Project Leader Mike McQuaid elected by acclamation. @@ -49,7 +48,7 @@ - 12:55–13:00 Shaun Jackman - Speeding up install times / Git repo size - 13:10 Meeting adjourned -## Motions +## Resolutions ### Motion to adopt the voting system diff --git a/docs/vale-styles/Homebrew/README.md b/docs/vale-styles/Homebrew/README.md index a713f91d75..ce3e0c3ac7 100644 --- a/docs/vale-styles/Homebrew/README.md +++ b/docs/vale-styles/Homebrew/README.md @@ -1 +1,3 @@ +# Vale Styles + Based on Homebrew's [Prose Style Guidelines](http://docs.brew.sh/Prose-Style-Guidelines.html).