Import docs from wiki.

Closes Homebrew/homebrew#33211.

1 files changed, 56 insertions, 0 deletions

diff --git a/share/doc/homebrew/Troubleshooting.md b/share/doc/homebrew/Troubleshooting.md
new file mode 100644
index 000000000..d6b2f2298
--- /dev/null
+++ b/share/doc/homebrew/Troubleshooting.md
@@ -0,0 +1,56 @@
+# Troubleshooting
+## Read this first!
+
+Please run `brew update` and `brew doctor` *before* creating an issue!
+
+If you create an issue, please also create a [Gist][] by running
+
+```
+brew gist-logs <formula name>
+```
+
+and include a link to the gist in the issue.
+
+Read on for more detailed instructions.
+
+Thank you!
+
+## Check for common issues
+* Run `brew update` — then try again.
+* Run `brew doctor` — the doctor diagnoses common issues.
+* Read through the [Common Issues](Common-Issues.md) page.
+* If you’re installing something Java-related, maybe you need the [Java Developer Update][] or [JDK 7][]?
+* Check that **Command Line Tools for Xcode (CLT)** and/or **Xcode** are up to date.
+* If things fail with permissions errors, check the permissions in `/usr/local`. If you’re unsure what to do, you can `sudo chown -R $(whoami) /usr/local`.
+
+#### Listen to Dr. Brew
+
+* **Update Xcode and/or Command Line Tools for Xcode!** Make sure that Xcode is up-to-date in the App Store. Check that the CLT package is up-to-date (either via Xcode, Preferences or at [Apple Developer][]).
+* If `brew doctor` warns about unbrewed dylibs, be advised that they are **very likely to cause build problems**.
+
+## Check to see if the issue has been reported
+* Browse open issues on the [issue tracker](https://github.com/Homebrew/homebrew/issues) to see if someone else has already reported the same problem.
+* 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.
+
+## Create an issue
+
+1. [Create a new issue](https://github.com/Homebrew/homebrew/issues/new)
+  * Again, make sure you file the issue against the correct repository.
+  * If you are reporting a build failure, title it "\<formula name> failed to build on 10.x", where \<formula name> is the name of the formula that failed to build, and 10.x is the version of OS X you are using.
+  * Otherwise, choose a title that best describes the problem you are experiencing.
+
+2. Upload a [Gist][] with relevant debugging information
+  * The simplest method is to run `brew gist-logs <formula name>`
+  * You can also create a [Gist][] manually. Include the following:
+     1. The output from `HOMEBREW_MAKE_JOBS=1 brew install -v <formula name> 2>&1`
+     2. The contents of the largest numbered log in `~/Library/Logs/Homebrew/<formula name>`, e.g. `03.make`
+     3. The output from `brew config` and `brew doctor`
+  * If you are reporting a bug rather than a build failure, please include `brew config`, `brew doctor`, and enough information to reliably reproduce the bug.
+
+3. Include a link to the gist in your new issue
+  * Be sure to use the `https:` URL (i.e. the URL in your browser's address bar), not the `git:` URL.
+
+[Gist]:https://gist.github.com
+[Apple Developer]:https://developer.apple.com/downloads
+[Java Developer Update]:http://support.apple.com/kb/DL1572
+[JDK 7]:http://docs.oracle.com/javase/7/docs/webnotes/install/mac/mac-install-faq.html