diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 2ccec5248b..511700200c 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -130,6 +130,12 @@ jobs: export PATH="/home/linuxbrew/.linuxbrew/bin:/usr/local/bin:/usr/bin:/bin" brew readall --aliases + - name: Run vale for docs linting + run: | + export PATH="/home/linuxbrew/.linuxbrew/bin:/usr/local/bin:/usr/bin:/bin" + brew install vale + vale $(brew --repo)/docs/ + - name: Build Docker image run: | docker pull homebrew/brew diff --git a/.gitignore b/.gitignore index 275f1cc6c2..94bfb9b2c9 100644 --- a/.gitignore +++ b/.gitignore @@ -154,6 +154,7 @@ !/.editorconfig !/.gitignore !/.yardopts +!/.vale.ini !/CHANGELOG.md !/CONTRIBUTING.md !/Dockerfile diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 0000000000..8aeb075101 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,4 @@ +StylesPath = ./docs/vale-styles + +[*.md] +BasedOnStyles = Homebrew diff --git a/Library/Homebrew/manpages/brew.1.md.erb b/Library/Homebrew/manpages/brew.1.md.erb index 2cdd3f9130..982a3378a7 100644 --- a/Library/Homebrew/manpages/brew.1.md.erb +++ b/Library/Homebrew/manpages/brew.1.md.erb @@ -9,7 +9,7 @@ # # When done, regenerate the man page and its HTML version by running `brew man`. %> -brew(1) -- The missing package manager for macOS +brew(1) -- The Missing Package Manager for macOS ================================================ ## SYNOPSIS diff --git a/docs/Bottles.md b/docs/Bottles.md index b0d68f4860..c52ad82926 100644 --- a/docs/Bottles.md +++ b/docs/Bottles.md @@ -1,4 +1,4 @@ -# Bottles (binary packages) +# Bottles (Binary Packages) Bottles are produced by installing a formula with `brew install --build-bottle ` and then bottling it with `brew bottle `. This outputs the bottle DSL which should be inserted into the formula file. diff --git a/docs/FAQ.md b/docs/FAQ.md index c22b9efb31..d7cc32c1aa 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -204,9 +204,9 @@ our analytics identified it was not widely used. ## Homebrew is a poor name, it's too generic, why was it chosen? @mxcl was too concerned with the beer theme and didn’t consider that the -project may actually prove popular. By the time he realised it was, it was too -late. However, today, the first Google hit for “homebrew” is not beer -related ;‑) +project may actually prove popular. By the time Max realised that it +was popular, it was too late. However, today, the first Google hit for +“homebrew” is not beer related ;‑) ## What does "keg-only" mean? It means the formula is installed only into the Cellar; it is not linked diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index e82499dc16..3c22509af6 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -732,9 +732,9 @@ Homebrew provides two formula DSL methods for launchd plist files: Homebrew has multiple levels of environment variable filtering which affects variables available to formulae. -Firstly, the overall environment in which Homebrew runs is filtered to avoid environment contamination breaking from-source builds (). In particular, this process filters all but the given whitelisted variables, but allows environment variables prefixed with `HOMEBREW_`. The specific implementation can be seen in [`bin/brew`](https://github.com/Homebrew/brew/blob/master/bin/brew). +Firstly, the overall environment in which Homebrew runs is filtered to avoid environment contamination breaking from-source builds (). In particular, this process filters all but the given whitelisted variables, but allows environment variables prefixed with `HOMEBREW_`. The specific implementation can be seen in [`bin/brew`](https://github.com/Homebrew/brew/blob/master/bin/brew). -The second level of filtering removes sensitive environment variables (such as credentials like keys, passwords or tokens) to avoid malicious subprocesses obtaining them (). This has the effect of preventing any such variables from reaching a formula's Ruby code as they are filtered before it is called. The specific implementation can be seen in the [`ENV.clear_sensitive_environment!` method](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/extend/ENV.rb). +The second level of filtering removes sensitive environment variables (such as credentials like keys, passwords or tokens) to avoid malicious subprocesses obtaining them (). This has the effect of preventing any such variables from reaching a formula's Ruby code as they are filtered before it is called. The specific implementation can be seen in the [`ENV.clear_sensitive_environment!` method](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/extend/ENV.rb). In summary, environment variables used by a formula need to conform to these filtering rules in order to be available. diff --git a/docs/Homebrew-linuxbrew-core-Maintainer-Guide.md b/docs/Homebrew-linuxbrew-core-Maintainer-Guide.md index ce5f5db501..3a838c6bc0 100644 --- a/docs/Homebrew-linuxbrew-core-Maintainer-Guide.md +++ b/docs/Homebrew-linuxbrew-core-Maintainer-Guide.md @@ -1,4 +1,4 @@ -# Homebrew linuxbrew-core Maintainer Guide +# Homebrew/linuxbrew-core Maintainer Guide ## Merging formulae updates from Homebrew/homebrew-core @@ -23,7 +23,7 @@ export HOMEBREW_NO_AUTO_UPDATE=1 Once we've done that, we need to get access to the `merge-homebrew` command that will be used for the merge. To do that we have to tap the [`Homebrew/linux-dev`](https://github.com/Homebrew/homebrew-linux-dev) -repo: +repository: ```bash brew tap homebrew/linux-dev @@ -235,7 +235,7 @@ against the formulae: And it skips formulae if any of the following are true: - it doesn't need a bottle - it already has a bottle -- the formula's tap is Homebrew/homebrew-core (the upstream macOS repo) +- the formula's tap is Homebrew/homebrew-core (the upstream macOS repository) - there is already an open PR for the formula's bottle - the current branch is not master diff --git a/docs/How-To-Open-a-Homebrew-Pull-Request.md b/docs/How-To-Open-a-Homebrew-Pull-Request.md index 0041845266..7d1a986df4 100644 --- a/docs/How-To-Open-a-Homebrew-Pull-Request.md +++ b/docs/How-To-Open-a-Homebrew-Pull-Request.md @@ -1,4 +1,4 @@ -# How To Open a Homebrew Pull Request (and get it merged) +# How To Open a Homebrew Pull Request The following commands are used by Homebrew contributors to set up a fork of Homebrew's Git repository on GitHub, create a new branch and create a GitHub pull request ("PR") of the changes in that branch. 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 similarity index 97% rename from docs/How-to-build-software-outside-Homebrew-with-Homebrew-keg-only-dependencies.md rename to docs/How-to-Build-Software-Outside-Homebrew-with-Homebrew-keg-only-Dependencies.md index 919c9b15e0..87bea3b3ac 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 @@ -1,4 +1,4 @@ -# How to build software outside Homebrew with Homebrew `keg_only` dependencies +# How to Build Software Outside Homebrew with Homebrew `keg_only` Dependencies ## What does "keg-only" mean? diff --git a/docs/Manpage.md b/docs/Manpage.md index 0c664701d2..2b0fbe73a0 100644 --- a/docs/Manpage.md +++ b/docs/Manpage.md @@ -1,4 +1,4 @@ -brew(1) -- The missing package manager for macOS +brew(1) -- The Missing Package Manager for macOS ================================================ ## SYNOPSIS diff --git a/docs/Prose-Style-Guidelines.md b/docs/Prose-Style-Guidelines.md index 3fa60676b5..5b2eabeec0 100644 --- a/docs/Prose-Style-Guidelines.md +++ b/docs/Prose-Style-Guidelines.md @@ -1,3 +1,5 @@ + + # Prose Style Guidelines This is a set of style and usage guidelines for Homebrew's prose documentation aimed at users, contributors, and maintainers (as opposed to executable computer code). It applies to documents like those in `docs` in the `Homebrew/brew` repository, announcement emails, and other communications with the Homebrew community. @@ -39,7 +41,7 @@ We prefer: ### Structure and markup -* Sentence case in section headings, not Title Case +* Title Case in `h1` headings; sentence case in all other headings * Periods at the ends of list items where most items in that list are complete sentences * More generally, parallel list item structure * Capitalise all list items if you want, even if they're not complete sentences; just be consistent within each list, and preferably, throughout the whole page @@ -86,3 +88,5 @@ Refer to these guidelines to make decisions about style and usage in your own wr PRs that fix style and usage throughout a document or multiple documents are okay and encouraged. PRs for just one or two style changes are a bit much. Giving style and usage feedback on a PR or commit that involves documents is okay and encouraged. But keep in mind that these are just guidelines, and for any change, the author may have made a deliberate choice to break these rules in the interest of understandability or aesthetics. + + diff --git a/docs/Taps.md b/docs/Taps.md index 9ed939a0f2..aa8748b85a 100644 --- a/docs/Taps.md +++ b/docs/Taps.md @@ -1,4 +1,4 @@ -# Taps (third-party repositories) +# Taps (Third-Party Repositories) `brew tap` adds more repositories to the list of formulae that `brew` tracks, updates, and installs from. By default, `tap` assumes that the repositories come from GitHub, @@ -16,12 +16,15 @@ mistydemeo/tigerbrew dunn/emacs ``` + + * `brew tap ` makes a shallow clone of the repository at https://github.com/user/repo. After that, `brew` will be able to work on those formulae as if they were in Homebrew's canonical repository. You can install and uninstall them with `brew [un]install`, and the formulae are automatically updated when you run `brew update`. (See below for details about how `brew tap` handles the names of repositories.) + * `brew tap ` makes a shallow clone of the repository at URL. Unlike the one-argument version, URL is not assumed to be GitHub, and it diff --git a/docs/_config.yml b/docs/_config.yml index 96bdaa69ef..8bffff2286 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -7,6 +7,7 @@ exclude: - bin - CNAME - Gemfile* + - vale-styles - vendor plugins: diff --git a/docs/vale-styles/Homebrew/Abbreviations.yml b/docs/vale-styles/Homebrew/Abbreviations.yml new file mode 100644 index 0000000000..95bd5b559e --- /dev/null +++ b/docs/vale-styles/Homebrew/Abbreviations.yml @@ -0,0 +1,12 @@ +--- +extends: substitution +message: Use '%s' +ignorecase: false +link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#style-and-usage' +level: error +nonword: true +swap: + '\beg\b': e.g. + '\bie\b': i.e. + 'e\.g\.,': e.g. + 'i\.e\.,': i.e. diff --git a/docs/vale-styles/Homebrew/OxfordComma.yml b/docs/vale-styles/Homebrew/OxfordComma.yml new file mode 100644 index 0000000000..26f258763e --- /dev/null +++ b/docs/vale-styles/Homebrew/OxfordComma.yml @@ -0,0 +1,8 @@ +--- +extends: existence +message: 'No Oxford commas!' +link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#typographical-conventions' +scope: sentence +level: warning +tokens: + - '(?:[^,]+,){1,}\s\w+,\sand' diff --git a/docs/vale-styles/Homebrew/Pronouns.yml b/docs/vale-styles/Homebrew/Pronouns.yml new file mode 100644 index 0000000000..f1d5f30c33 --- /dev/null +++ b/docs/vale-styles/Homebrew/Pronouns.yml @@ -0,0 +1,15 @@ +--- +extends: existence +message: Avoid gender-specific language when not necessary. +link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#personal-pronouns' +level: warning +ignorecase: true +tokens: + - him + - her + - she + - he + - his + - hers + - himself + - herself diff --git a/docs/vale-styles/Homebrew/README.md b/docs/vale-styles/Homebrew/README.md new file mode 100644 index 0000000000..a713f91d75 --- /dev/null +++ b/docs/vale-styles/Homebrew/README.md @@ -0,0 +1 @@ +Based on Homebrew's [Prose Style Guidelines](http://docs.brew.sh/Prose-Style-Guidelines.html). diff --git a/docs/vale-styles/Homebrew/Spacing.yml b/docs/vale-styles/Homebrew/Spacing.yml new file mode 100644 index 0000000000..2b3f2bdc10 --- /dev/null +++ b/docs/vale-styles/Homebrew/Spacing.yml @@ -0,0 +1,9 @@ +--- +extends: existence +message: "'%s' should have one space." +link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#typographical-conventions' +level: error +nonword: true +tokens: + - '[a-z][.?!][A-Z]' + - '[.?!] {2,}[A-Z]' diff --git a/docs/vale-styles/Homebrew/Terms.yml b/docs/vale-styles/Homebrew/Terms.yml new file mode 100644 index 0000000000..5262e5df1b --- /dev/null +++ b/docs/vale-styles/Homebrew/Terms.yml @@ -0,0 +1,10 @@ +--- +extends: substitution +message: Use '%s' instead of '%s'. +link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#terminology-words-and-word-styling' +level: error +scope: $paragraph +swap: + Pull Request: pull request + repo: repository + Rubocop: RuboCop diff --git a/docs/vale-styles/Homebrew/Titles.yml b/docs/vale-styles/Homebrew/Titles.yml new file mode 100644 index 0000000000..f546c7e745 --- /dev/null +++ b/docs/vale-styles/Homebrew/Titles.yml @@ -0,0 +1,10 @@ +extends: capitalization +message: "'%s' should be in title case" +level: warning +scope: heading.h1 +match: $title +style: AP +exceptions: + - brew(1) + - Homebrew/homebrew-core + - Homebrew/linuxbrew-core diff --git a/docs/vale-styles/Homebrew/Trademarks.yml b/docs/vale-styles/Homebrew/Trademarks.yml new file mode 100644 index 0000000000..e1d335d46c --- /dev/null +++ b/docs/vale-styles/Homebrew/Trademarks.yml @@ -0,0 +1,12 @@ +--- +extends: existence +message: 'No "TM", ™, SM, ©, ®, or other explicit indicators of rights ownership or trademarks' +link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#typographical-conventions' +level: error +nonword: true +tokens: + - \bTM\b + - ™ + - \bSM\b + - © + - ® diff --git a/manpages/brew.1 b/manpages/brew.1 index 7cca55a2eb..5d815e774c 100644 --- a/manpages/brew.1 +++ b/manpages/brew.1 @@ -4,7 +4,7 @@ .TH "BREW" "1" "December 2019" "Homebrew" "brew" . .SH "NAME" -\fBbrew\fR \- The missing package manager for macOS +\fBbrew\fR \- The Missing Package Manager for macOS . .SH "SYNOPSIS" \fBbrew\fR \fB\-\-version\fR