Revamp reporting bugs docs (Homebrew#57844)

.github/ISSUE_TEMPLATE/01_bug_report.md

@@ -6,11 +6,11 @@ about: Create a report to help us improve
 
 #### General troubleshooting steps
 
-- [ ] I have retried my command with `--force` and the issue is still present.
-- [ ] I have checked the instructions for [reporting bugs](https://github.com/Homebrew/homebrew-cask#reporting-bugs).
-- [ ] I made doubly sure this is not a [checksum does not match](https://github.com/Homebrew/homebrew-cask/blob/master/doc/reporting_bugs/a_cask_fails_to_install.md#checksum-does-not-match-error) error.
+- [ ] I have retried my command with `--force`.
 - [ ] I ran `brew update-reset && brew update` and retried my command.
 - [ ] I ran `brew doctor`, fixed as many issues as possible and retried my command.
+- [ ] I have checked the instructions for [reporting bugs](https://github.com/Homebrew/homebrew-cask#reporting-bugs).
+- [ ] I made doubly sure this is not a [checksum does not match](https://github.com/Homebrew/homebrew-cask/blob/master/doc/reporting_bugs/checksum_does_not_match_error.md) error.
 - [ ] I checked there are no [open issues](https://github.com/Homebrew/homebrew-cask/issues) for the same problem.
 - [ ] I understand that [if I ignore these instructions, my issue may be closed without review](https://github.com/Homebrew/homebrew-cask/blob/master/doc/faq/closing_issues_without_review.md).
 

README.md

@@ -42,22 +42,19 @@ And there we have it. Atom installed with one quick command: no clicking, no dra
 
 [**If you ignore this guide, your issue may be closed without review**](doc/faq/closing_issues_without_review.md).
 
-Before reporting a bug, run `brew update-reset && brew update` and try your command again. This will ensure the problem isn’t an outdated setup on your side. Note this command is a fix-all that will reset the state of all your taps, so if you have changes on those that you want to keep, deal with them first.
+Before reporting a bug, run `brew update-reset && brew update` and try your command again. This is a fix-all that will reset the state of all your taps, ensuring the problem isn’t an outdated setup on your side.
 
-If your issue persists, search for it before opening a new one. If you find an open issue and have any new information not reported in the original, please add your insights. If you find a closed issue, try the solutions there.
+If your issue persists, [search for it](https://github.com/Homebrew/homebrew-cask/search?type=Issues) before opening a new one. If you find an open issue and have any new information, add it in a comment. If you find a closed issue, try the solutions there.
 
- If the issue is still not solved, see the guides for common problems:
+If the issue is still not solved, see the guides for common problems:
 
-* A cask fails to install:
-  * [`curl` error](doc/reporting_bugs/a_cask_fails_to_install.md#curl-error)
-  * [`Permission denied` error](doc/reporting_bugs/a_cask_fails_to_install.md#permission-denied-error)
-  * [`Checksum does not match` error](doc/reporting_bugs/a_cask_fails_to_install.md#checksum-does-not-match-error)
-  * [`source is not there` error](doc/reporting_bugs/a_cask_fails_to_install.md#source-is-not-there-error)
-  * [`wrong number of arguments` error](doc/reporting_bugs/a_cask_fails_to_install.md#wrong-number-of-arguments-error)
-  * [Unlisted reason](doc/reporting_bugs/a_cask_fails_to_install.md#unlisted-reason)
+* [Examples of common errors and their solutions](doc/reporting_bugs/error_examples.md)
+* [`curl` error](doc/reporting_bugs/curl_error.md)
+* [`Permission denied` error](doc/reporting_bugs/permission_denied_error.md)
+* [`Checksum does not match` error](doc/reporting_bugs/checksum_does_not_match_error.md)
+* [`source is not there` error](doc/reporting_bugs/source_is_not_there_error.md)
+* [`wrong number of arguments` error](doc/reporting_bugs/wrong_number_of_arguments_error.md)
 * [The app can’t be opened because it is from an unidentified developer](doc/faq/the_app_cant_be_opened.md)
-* [`uninstall` wrongly reports cask as not installed](doc/reporting_bugs/uninstall_wrongly_reports_cask_as_not_installed.md)
-* [`Error: Unknown command: cask` error](doc/reporting_bugs/error_unknown_command_cask.md)
 * [My problem isn’t listed](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md)
 
 ## Requests

doc/reporting_bugs/checksum_does_not_match_error.md

@@ -0,0 +1,10 @@
+First, check if the problem was with your download. Delete the downloaded file (its location will be pointed out right under the `Actual` shasum line) and try again.
+
+If the problem persists, the cask must be outdated. It’ll likely need a new version, but it’s possible the version has remained the same (happens occasionally when the vendor updates the app in place).
+
+1. Go to the vendor’s website (`brew cask home {{cask_name}}`).
+    * Alternatively, if it has an `appcast`, read that (`curl "$(brew cask _stanza appcast {{cask_name}})"`).
+2. Find out what the latest version is. It will likely be expressed in the URL used to download it.
+3. Take a look at the cask’s version (`brew cask _stanza version {{cask_name}}`) and verify it is indeed outdated. If it is:
+
+Help us by [submitting a fix](https://github.com/Homebrew/homebrew-cask/blob/master/CONTRIBUTING.md#updating-a-cask). If you get stumped, [open an issue](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md) explaining your steps so far and where you’re having trouble.

doc/reporting_bugs/curl_error.md

@@ -0,0 +1,26 @@
+First, let's tackle a common problem: do you have a `.curlrc` file? Check with `ls -A ~ | grep .curlrc` (if you get a result, the file exists). Those are a frequent cause of issues of this nature. Before anything else, remove that file and try again. If it now works, do not open an issue. Incompatible `.curlrc` configurations must be fixed on your side.
+
+If, however, you do not have a `.curlrc` or removing it did not work, let’s see if the issue is upstream:
+
+1. Go to the vendor’s website (`brew cask home {{cask_name}}`).
+2. Find the download link for the app and click on it.
+
+#### If the download works
+
+The cask is outdated. Let’s fix it:
+
+1. Look around the app’s website and find out what the latest version is. It will likely be expressed in the URL used to download it.
+2. Take a look at the cask’s version (`brew cask _stanza version {{cask_name}}`) and verify it is indeed outdated.
+  * If the app’s version is `latest`, it means the `url` itself is outdated. It will need to be changed to the new one.
+
+Help us by [submitting a fix](https://github.com/Homebrew/homebrew-cask/blob/master/CONTRIBUTING.md#updating-a-cask). If you get stumped, [open an issue](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md) explaining your steps so far and where you’re having trouble.
+
+#### If the download does not work
+
+The issue isn’t in any way related to Homebrew Cask, but with the vendor or your connection.
+
+Start by diagnosing your connection (try to download other casks, go around the web). If the problem is with your connection, try a website like [Ask Different](https://apple.stackexchange.com/) to ask for advice.
+
+If you’re sure the issue is not with your connection, contact the app’s vendor and let them know their link is down, so they can fix it.
+
+**Do not open an issue.**

doc/reporting_bugs/a_cask_fails_to_install.md → doc/reporting_bugs/error_examples.md

@@ -1,10 +1,4 @@
-<sup><sub>[Go back](../../README.md#reporting-bugs)</sup></sub>
-
-# A cask fails to install
-
-Pick the issue closest to your case, and follow the links.
-
----
+Examples of common errors and their solutions
 
 #### `curl` error:
 
@@ -16,11 +10,11 @@ curl: (22) The requested URL returned error: 403 Forbidden
 
 the problem was with the downloading itself (see how the error came from `curl`). Homebrew Cask itself is fine and the problem is generally one of:
 
-1. App vendor or file in their server is down.
+1. Software vendor or the file in their server is down.
 2. Cask is outdated.
 3. A problem in your setup or connection.
 
-[Continue to the fix](curl_error_fix_curlrc.md)
+[How to fix](curl_error.md)
 
 ---
 
@@ -34,7 +28,7 @@ Error: Permission denied - (/usr/local/Caskroom/someapp/0.1/Someapp.app, /Applic
 
 the problem isn’t with Homebrew Cask itself, but some permissions on your system.
 
-[Continue to the fix](permission_denied_error_fix_appdir.md)
+[How to fix](permission_denied_error.md)
 
 ---
 
@@ -51,7 +45,7 @@ Actual: 526d747d99a93b760f7965e25a57ed61de9b93d566a0ba0c5f1c7e83719b20fd
 
 either your download was incomplete/corrupt or the cask is outdated.
 
-[Continue to the fix](checksum_does_not_match_error_fix_icomplete.md)
+[How to fix](checksum_does_not_match_error.md)
 
 ---
 
@@ -60,12 +54,12 @@ either your download was incomplete/corrupt or the cask is outdated.
 If the error output includes something like
 
 ```
-Error: It seems the App source is not there: '/usr/local/Caskroom/…'
+It seems the App source '/usr/local/Caskroom/someapp/0.1/Someapp.app' is not there.
 ```
 
 the directory structure inside the app’s archive changed in some way. It must be fixed in Homebrew Cask.
 
-[Continue to the fix](source_is_not_there_fix.md)
+[How to fix](source_is_not_there_error.md)
 
 ---
 
@@ -79,10 +73,10 @@ Error: wrong number of arguments (1 for 4)
 
 it’s likely the software you’re trying to install is incompatible with your macOS version.
 
-[Continue to the fix](wrong_number_of_arguments_fix.md)
+[How to fix](wrong_number_of_arguments_error.md)
 
 ---
 
 #### Unlisted reason
 
-If your issue isn’t listed here, [go back](../../README.md#reporting-bugs) and pick `My problem isn’t listed`.
+If your issue isn’t listed here, [go back](https://github.com/Homebrew/homebrew-cask/blob/master/README.md#reporting-bugs) and pick `My problem isn’t listed`.

doc/reporting_bugs/permission_denied_error.md

@@ -0,0 +1,7 @@
+In this case, it’s likely your user account has no admin rights so you don’t have permissions to write to `/Applications` (which is the default). You can use [`--appdir`](https://github.com/Homebrew/homebrew-cask/blob/master/USAGE.md#options) to choose where to install your applications.
+
+If `--appdir` doesn’t fix the issue or you do have write permissions to `/Applications`, the problem may lie in the app bundle itself.
+
+Some app bundles don’t have certain permissions that are necessary for us to move them to the appropriate location. You may check such permissions with `ls -ls {{path_to_app_bundle}}`. If you see something like `dr-xr-xr-x` at the start of the output, that may be the cause. To fix it, we simply change the app bundle’s permission to allow us to move it, and then set it back to what it was (in case the developer set those permissions deliberately). See [`litecoin`](https://github.com/Homebrew/homebrew-cask/blob/0cde71f1fea8ad62d6ec4732fcf35ac0c52d8792/Casks/litecoin.rb#L14L20) for an example of such a cask.
+
+Help us by [submitting a fix](https://github.com/Homebrew/homebrew-cask/blob/master/CONTRIBUTING.md#updating-a-cask). If you get stumped, [open an issue](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md) explaining your steps so far and where you’re having trouble.