From 459d732714d94a574fa6525f04a3ee04a36be353 Mon Sep 17 00:00:00 2001 From: Daniel D. Beck Date: Sun, 6 Nov 2016 17:43:49 +0000 Subject: put troubleshooting steps in order of specificity --- docs/Troubleshooting.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md index 4fc77d6cd..0ba5ed73e 100644 --- a/docs/Troubleshooting.md +++ b/docs/Troubleshooting.md @@ -10,10 +10,11 @@ brew gist-logs ## Check for common issues * Run `brew update` (twice). * Run `brew doctor` and fix all the warnings (**outdated Xcode/CLT and unbrewed dylibs are very likely to cause problems**). -* Read through the [Common Issues](Common-Issues.md). -* If you’re installing something Java-related, maybe you need to install Java (`brew cask install java`)? * Check that **Command Line Tools for Xcode (CLT)** and/or **Xcode** are up to date. * If things fail with permissions errors, check the permissions of `/usr/local`'s subdirectories. If you’re unsure what to do, you can `cd /usr/local && sudo chown -R $(whoami) bin etc include lib sbin share var Frameworks`. +* Read through the [Common Issues](Common-Issues.md). +* If you’re installing something Java-related, maybe you need to install Java (`brew cask install java`)? + ## Check to see if the issue has been reported * Check the [issue tracker](https://github.com/Homebrew/homebrew-core/issues) to see if someone else has already reported the same issue. -- cgit v1.2.3 From 36431d94b8cfeac0428c67919e324a9bc5b7c6c9 Mon Sep 17 00:00:00 2001 From: Daniel D. Beck Date: Sun, 6 Nov 2016 17:51:26 +0000 Subject: stop short-circuiting the common issues troubleshooting steps --- docs/Troubleshooting.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md index 0ba5ed73e..25a684ae5 100644 --- a/docs/Troubleshooting.md +++ b/docs/Troubleshooting.md @@ -1,11 +1,6 @@ # Troubleshooting -**Run `brew update` (twice) and `brew doctor` *before* creating an issue!** -When creating a formula-related issue please include the link output by running: - -```shell -brew gist-logs -``` +Before creating an issue, check for common issues and make sure your issue has not already been reported. ## Check for common issues * Run `brew update` (twice). -- cgit v1.2.3 From 20e48d8df6349c436f8223eb189d0725f4695c95 Mon Sep 17 00:00:00 2001 From: Daniel D. Beck Date: Sun, 6 Nov 2016 18:15:58 +0000 Subject: revise troubleshooting doc --- docs/Troubleshooting.md | 30 +++++++++++++++++++++--------- 1 file changed, 21 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md index 25a684ae5..79273d298 100644 --- a/docs/Troubleshooting.md +++ b/docs/Troubleshooting.md @@ -2,21 +2,33 @@ Before creating an issue, check for common issues and make sure your issue has not already been reported. + ## Check for common issues -* Run `brew update` (twice). + +Follow these steps to fix common problems: + +* Run `brew update` twice. * Run `brew doctor` and fix all the warnings (**outdated Xcode/CLT and unbrewed dylibs are very likely to cause problems**). -* Check that **Command Line Tools for Xcode (CLT)** and/or **Xcode** are up to date. -* If things fail with permissions errors, check the permissions of `/usr/local`'s subdirectories. If you’re unsure what to do, you can `cd /usr/local && sudo chown -R $(whoami) bin etc include lib sbin share var Frameworks`. +* Check that **Command Line Tools for Xcode (CLT)** and **Xcode** are up to date. +* If commands fail with permissions errors, check the permissions of `/usr/local`'s subdirectories. If you’re unsure what to do, you can run `cd /usr/local && sudo chown -R $(whoami) bin etc include lib sbin share var Frameworks`. * Read through the [Common Issues](Common-Issues.md). -* If you’re installing something Java-related, maybe you need to install Java (`brew cask install java`)? +* If you’re installing something Java-related, make sure you have installed Java (you can run `brew cask install java`). ## Check to see if the issue has been reported -* Check the [issue tracker](https://github.com/Homebrew/homebrew-core/issues) to see if someone else has already reported the same issue. -* Make sure you check issues on the correct repository. If the formula that failed to build is part of a tap like [homebrew/science](https://github.com/Homebrew/homebrew-science) or [homebrew/dupes](https://github.com/Homebrew/homebrew-dupes) check there instead. + +* Search the [issue tracker](https://github.com/Homebrew/homebrew-core/issues) to see if someone else has already reported the same issue. +* Make sure you search issues on the correct repository. If a formula that has failed to build is part of a tap like [homebrew/science](https://github.com/Homebrew/homebrew-science/issues) or [homebrew/dupes](https://github.com/Homebrew/homebrew-dupes/issues) check those issue trackers instead. + ## Create an issue + +If your problem hasn't been solved or reported, then create an issue: + 0. Upload debugging information to a [Gist](https://gist.github.com): - - If you had a formula error: run `brew gist-logs ` (where `` is the name of the formula that failed to build). - - If you encountered a non-formula bug: upload the output of `brew config` and `brew doctor` to a new [Gist](https://gist.github.com). -1. [Create a new issue](https://github.com/Homebrew/homebrew-core/issues/new) titled "\ failed to build on 10.x", where `` is the name of the formula that failed to build, and `10.x` is the version of macOS you are using and including the link output by `brew gist-logs` + - If you had a formula-related problem: run `brew gist-logs ` (where `` is the name of the formula). + - If you encountered a non-formula problem: upload the output of `brew config` and `brew doctor` to a new [Gist](https://gist.github.com). +1. [Create a new issue](https://github.com/Homebrew/homebrew-core/issues/new). + - Give your issue a descriptive title which includes the formula name (if applicable) and the version of macOS you are using. For example, if a formula fails to build, title your issue "\ failed to build on \<10.x>", where "\" is the name of the formula that failed to build, and "\<10.x>" is the version of macOS you are using. + - Include the URL output by `brew gist-logs ` (if applicable). + - Include links to any additional Gists you may have created (such as for the output of `brew config` and `brew doctor`). -- cgit v1.2.3 From 0532e1e06a35d8ab133f919a69865bddd760f34e Mon Sep 17 00:00:00 2001 From: Daniel D. Beck Date: Mon, 7 Nov 2016 18:15:10 +0000 Subject: restore the more forceful introduction to the Troubleshooting doc --- docs/Troubleshooting.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md index 79273d298..e77f88903 100644 --- a/docs/Troubleshooting.md +++ b/docs/Troubleshooting.md @@ -1,6 +1,8 @@ # Troubleshooting -Before creating an issue, check for common issues and make sure your issue has not already been reported. +**Run `brew update` twice and `brew doctor` *before* creating an issue!** + +This document will help you check for common issues and make sure your issue has not already been reported. ## Check for common issues -- cgit v1.2.3