From 67cf535bce24ce6a65fe635aebfcda9d97cb37c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADtor=20Galv=C3=A3o?= Date: Thu, 24 Jan 2019 16:15:27 +0000 Subject: [PATCH] Revamp reporting bugs docs (#57844) --- .github/ISSUE_TEMPLATE/01_bug_report.md | 6 ++--- README.md | 21 +++++++-------- .../checksum_does_not_match_error.md | 10 +++++++ ...ksum_does_not_match_error_fix_icomplete.md | 5 ---- ...cksum_does_not_match_error_fix_outdated.md | 11 -------- doc/reporting_bugs/curl_error.md | 26 +++++++++++++++++++ doc/reporting_bugs/curl_error_fix_curlrc.md | 5 ---- .../curl_error_fix_no_download.md | 9 ------- doc/reporting_bugs/curl_error_fix_outdated.md | 9 ------- doc/reporting_bugs/curl_error_fix_vendor.md | 8 ------ doc/reporting_bugs/curl_error_fix_wont_fix.md | 9 ------- ..._fails_to_install.md => error_examples.md} | 24 +++++++---------- .../error_unknown_command_cask.md | 13 ---------- doc/reporting_bugs/permission_denied_error.md | 7 +++++ .../permission_denied_error_fix_appdir.md | 7 ----- .../permission_denied_error_fix_bundle.md | 5 ---- ...re_fix.md => source_is_not_there_error.md} | 6 ++--- ...l_wrongly_reports_cask_as_not_installed.md | 11 -------- .../wrong_number_of_arguments_error.md | 3 +++ .../wrong_number_of_arguments_fix.md | 5 ---- 20 files changed, 69 insertions(+), 131 deletions(-) create mode 100644 doc/reporting_bugs/checksum_does_not_match_error.md delete mode 100644 doc/reporting_bugs/checksum_does_not_match_error_fix_icomplete.md delete mode 100644 doc/reporting_bugs/checksum_does_not_match_error_fix_outdated.md create mode 100644 doc/reporting_bugs/curl_error.md delete mode 100644 doc/reporting_bugs/curl_error_fix_curlrc.md delete mode 100644 doc/reporting_bugs/curl_error_fix_no_download.md delete mode 100644 doc/reporting_bugs/curl_error_fix_outdated.md delete mode 100644 doc/reporting_bugs/curl_error_fix_vendor.md delete mode 100644 doc/reporting_bugs/curl_error_fix_wont_fix.md rename doc/reporting_bugs/{a_cask_fails_to_install.md => error_examples.md} (68%) delete mode 100644 doc/reporting_bugs/error_unknown_command_cask.md create mode 100644 doc/reporting_bugs/permission_denied_error.md delete mode 100644 doc/reporting_bugs/permission_denied_error_fix_appdir.md delete mode 100644 doc/reporting_bugs/permission_denied_error_fix_bundle.md rename doc/reporting_bugs/{source_is_not_there_fix.md => source_is_not_there_error.md} (63%) delete mode 100644 doc/reporting_bugs/uninstall_wrongly_reports_cask_as_not_installed.md create mode 100644 doc/reporting_bugs/wrong_number_of_arguments_error.md delete mode 100644 doc/reporting_bugs/wrong_number_of_arguments_fix.md diff --git a/.github/ISSUE_TEMPLATE/01_bug_report.md b/.github/ISSUE_TEMPLATE/01_bug_report.md index 3c1da6cbe1fae..3ec399e684060 100644 --- a/.github/ISSUE_TEMPLATE/01_bug_report.md +++ b/.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). diff --git a/README.md b/README.md index 0805ef8138110..fa2d0d1e92884 100644 --- a/README.md +++ b/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 diff --git a/doc/reporting_bugs/checksum_does_not_match_error.md b/doc/reporting_bugs/checksum_does_not_match_error.md new file mode 100644 index 0000000000000..2080aefd5b200 --- /dev/null +++ b/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. diff --git a/doc/reporting_bugs/checksum_does_not_match_error_fix_icomplete.md b/doc/reporting_bugs/checksum_does_not_match_error_fix_icomplete.md deleted file mode 100644 index 8fdc89877e698..0000000000000 --- a/doc/reporting_bugs/checksum_does_not_match_error_fix_icomplete.md +++ /dev/null @@ -1,5 +0,0 @@ -[Go back](a_cask_fails_to_install.md#checksum-does-not-match-error) - -First, let's see 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](checksum_does_not_match_error_fix_outdated.md). diff --git a/doc/reporting_bugs/checksum_does_not_match_error_fix_outdated.md b/doc/reporting_bugs/checksum_does_not_match_error_fix_outdated.md deleted file mode 100644 index d647dd58209e3..0000000000000 --- a/doc/reporting_bugs/checksum_does_not_match_error_fix_outdated.md +++ /dev/null @@ -1,11 +0,0 @@ -[Go back](checksum_does_not_match_error_fix_icomplete.md) - -Let's bring the cask up to date. 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 the app’s version is `latest`, it means the `url` itself is outdated. It will need to be changed to the new one. - -If it is outdated, start by trying to [submit a fix](../../CONTRIBUTING.md#updating-a-cask). If you’re having trouble, [open an issue](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md) explaining your steps so far and why you’re having trouble submitting the update. diff --git a/doc/reporting_bugs/curl_error.md b/doc/reporting_bugs/curl_error.md new file mode 100644 index 0000000000000..bc02f0192c6d6 --- /dev/null +++ b/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.** diff --git a/doc/reporting_bugs/curl_error_fix_curlrc.md b/doc/reporting_bugs/curl_error_fix_curlrc.md deleted file mode 100644 index 889643a1af7f8..0000000000000 --- a/doc/reporting_bugs/curl_error_fix_curlrc.md +++ /dev/null @@ -1,5 +0,0 @@ -[Go back](a_cask_fails_to_install.md#curl-error) - -First, let's tackle a common problem: do you have a `.curlrc` file? 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 [continue our diagnosis](curl_error_fix_vendor.md). diff --git a/doc/reporting_bugs/curl_error_fix_no_download.md b/doc/reporting_bugs/curl_error_fix_no_download.md deleted file mode 100644 index 71606d93d9fe4..0000000000000 --- a/doc/reporting_bugs/curl_error_fix_no_download.md +++ /dev/null @@ -1,9 +0,0 @@ -[Go back](curl_error_fix_vendor.md) - -There are a few reasons why you might not be finding a download: - -* You can’t access the vendor’s website at all. [Continue here](curl_error_fix_wont_fix.md). -* You can access the vendor’s site but they’re informing you the app is now discontinued. Submit a pull request deleting the cask or [open an issue][01_bug_report] informing us of the situation. -* You can access the vendor’s site but you cannot find the download link. [Open an issue][01_bug_report] and detail all your steps so far. - -[01_bug_report]: https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md diff --git a/doc/reporting_bugs/curl_error_fix_outdated.md b/doc/reporting_bugs/curl_error_fix_outdated.md deleted file mode 100644 index a76f1d9ac2b1e..0000000000000 --- a/doc/reporting_bugs/curl_error_fix_outdated.md +++ /dev/null @@ -1,9 +0,0 @@ -[Go back](curl_error_fix_vendor.md) - -Since the download started, it likely means 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. - -If it is outdated, start by trying to [submit a fix](../../CONTRIBUTING.md#updating-a-cask). If you’re having trouble, [open an issue](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md) explaining your steps so far and why you’re having trouble submitting the update. diff --git a/doc/reporting_bugs/curl_error_fix_vendor.md b/doc/reporting_bugs/curl_error_fix_vendor.md deleted file mode 100644 index 281e45542198f..0000000000000 --- a/doc/reporting_bugs/curl_error_fix_vendor.md +++ /dev/null @@ -1,8 +0,0 @@ -[Go back](curl_error_fix_curlrc) - -Let's now 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. - -Does it download? [Yes](curl_error_fix_outdated.md) | [No](curl_error_fix_wont_fix.md) | [There is nothing to download](curl_error_fix_no_download.md) diff --git a/doc/reporting_bugs/curl_error_fix_wont_fix.md b/doc/reporting_bugs/curl_error_fix_wont_fix.md deleted file mode 100644 index f4c3e5d5ad03b..0000000000000 --- a/doc/reporting_bugs/curl_error_fix_wont_fix.md +++ /dev/null @@ -1,9 +0,0 @@ -[Go back](curl_error_fix_vendor.md) - -This means 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.** diff --git a/doc/reporting_bugs/a_cask_fails_to_install.md b/doc/reporting_bugs/error_examples.md similarity index 68% rename from doc/reporting_bugs/a_cask_fails_to_install.md rename to doc/reporting_bugs/error_examples.md index 9c328b0c37675..a9aef97b7fe5c 100644 --- a/doc/reporting_bugs/a_cask_fails_to_install.md +++ b/doc/reporting_bugs/error_examples.md @@ -1,10 +1,4 @@ -[Go back](../../README.md#reporting-bugs) - -# 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`. diff --git a/doc/reporting_bugs/error_unknown_command_cask.md b/doc/reporting_bugs/error_unknown_command_cask.md deleted file mode 100644 index 13583cb1e4cf1..0000000000000 --- a/doc/reporting_bugs/error_unknown_command_cask.md +++ /dev/null @@ -1,13 +0,0 @@ -[Go back](../../README.md#reporting-bugs) - -# `Error: Unknown command: cask` error - -If you run into `Error: Unknown command: cask` while trying to use any `brew cask` command, please run the below command to fix things: - -`cd $(brew --repo); git fetch; git reset --hard origin/master; brew update` - - - -**Do not open an issue.** - -(*Technical details:* Homebrew Cask's core code [has been moved](https://github.com/Homebrew/brew/pull/725) to Homebrew. `brew` had a [bug](https://github.com/Homebrew/brew/blob/7395ff20018785bed7d008337b7cf98781190e0a/README.md#update-bug) where it would erroneously report as always being `Already up-to-date.` This combination made it impossible for Homebrew to find the moved Cask code.) diff --git a/doc/reporting_bugs/permission_denied_error.md b/doc/reporting_bugs/permission_denied_error.md new file mode 100644 index 0000000000000..b87ff0d013dfd --- /dev/null +++ b/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. diff --git a/doc/reporting_bugs/permission_denied_error_fix_appdir.md b/doc/reporting_bugs/permission_denied_error_fix_appdir.md deleted file mode 100644 index 509e1ed0998f9..0000000000000 --- a/doc/reporting_bugs/permission_denied_error_fix_appdir.md +++ /dev/null @@ -1,7 +0,0 @@ -[Go back](a_cask_fails_to_install.md#permission-denied-error) - -In this case, it’s likely you’re a standard user and don’t have permissions to write to `/Applications` (which is now our default). If you never changed your default installation directory for apps and were using Homebrew Cask before we changed our behaviour to moving apps instead of linking, you should have some symlinks in your `~/Applications` directory, which you do have permission to write to. - -You can use `--appdir=~/Applications` when installing to bring back the old behaviour. For a permanent change, [follow the `Options` section in `USAGE.md`](https://github.com/Homebrew/homebrew-cask/blob/1de4657a0ed35463602b31061b0c16dc9078b8a0/USAGE.md#options). Specifically, you’ll want to set `export HOMEBREW_CASK_OPTS="--appdir=~/Applications"` in your shell’s startup file. - -If `--appdir` doesn’t fix the issue or you do have write permissions to `/Applications`, the problem may lie [in the app bundle itself](permission_denied_error_fix_bundle.md). diff --git a/doc/reporting_bugs/permission_denied_error_fix_bundle.md b/doc/reporting_bugs/permission_denied_error_fix_bundle.md deleted file mode 100644 index 2ab6937ce6fce..0000000000000 --- a/doc/reporting_bugs/permission_denied_error_fix_bundle.md +++ /dev/null @@ -1,5 +0,0 @@ -[Go back](permission_denied_error_fix_appdir.md) - -Some app bundles don’t have certain permissions that might be 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. - -If you’ve made the change and the issue persists or you’re having trouble making the change, [go back](../../README.md#reporting-bugs) and pick `My problem isn’t listed`. Be sure to mention all your steps so far and what you’re having difficulties with. diff --git a/doc/reporting_bugs/source_is_not_there_fix.md b/doc/reporting_bugs/source_is_not_there_error.md similarity index 63% rename from doc/reporting_bugs/source_is_not_there_fix.md rename to doc/reporting_bugs/source_is_not_there_error.md index dfc8e83ccddd2..9a8ec409caefd 100644 --- a/doc/reporting_bugs/source_is_not_there_fix.md +++ b/doc/reporting_bugs/source_is_not_there_error.md @@ -1,6 +1,4 @@ -[Go back](a_cask_fails_to_install.md#source-is-not-there-error) - -First, you need to identify which artifact is not being handled correctly anymore. It’s explicit in the error message: if it says `Error: It seems the App source…'` the problem is [`app`](https://github.com/Homebrew/homebrew-cask/blob/master/doc/cask_language_reference/stanzas/app.md). The pattern is the same across all artifacts. +First, you need to identify which artifact is not being handled correctly anymore. It’s explicit in the error message: if it says `It seems the App source…'` the problem is [`app`](https://github.com/Homebrew/homebrew-cask/blob/master/doc/cask_language_reference/stanzas/app.md). The pattern is the same across [all artifacts](https://github.com/Homebrew/homebrew-cask/blob/master/doc/cask_language_reference/all_stanzas.md#at-least-one-artifact-stanza-is-also-required). Fixing this error is typically easy, and requires only a bit of time on your part. Start by downloading the package for the cask: `brew cask fetch {{cask_name}}`. The last line of output will inform you of the location of the download. Navigate there and manually unpack it. As an example, lets say the structure inside the archive is as follows: @@ -23,4 +21,4 @@ The cask was expecting `SomeApp.app` to be in the top directory of the archive ( Note that occasionally the app’s name changes completely (from `SomeApp.app` to `OtherApp.app`, let's say). In these instances, the filename of the cask itself, as well as its token, must also change. Consult the [`token reference`](https://github.com/Homebrew/homebrew-cask/blob/master/doc/cask_language_reference/token_reference.md) for complete instructions on the new name. -Follow the instructions to [submit a fix](../../CONTRIBUTING.md#updating-a-cask), and make the change to the cask. If using `cask-repair`, you may give it the `--edit-cask` flag when calling it on the command-line to step right into editing it. If you’re having trouble, [open an issue](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md) explaining your steps so far and why you’re having trouble submitting the update. +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. diff --git a/doc/reporting_bugs/uninstall_wrongly_reports_cask_as_not_installed.md b/doc/reporting_bugs/uninstall_wrongly_reports_cask_as_not_installed.md deleted file mode 100644 index d602cf8031088..0000000000000 --- a/doc/reporting_bugs/uninstall_wrongly_reports_cask_as_not_installed.md +++ /dev/null @@ -1,11 +0,0 @@ -[Go back](../../README.md#reporting-bugs) - -# `uninstall` wrongly reports cask as not installed - -Reports of this bug are usually accompanied with the output of `brew cask list` showing the cask is indeed installed. [You should not rely on `brew cask list`](https://github.com/Homebrew/homebrew-cask/issues/14058) anyway, and this error is somewhat related to it. - -This is prone to happen when you try to uninstall a cask that has been updated since you last installed, or when a cask no longer exists in the repo (`brew cask list` will show it with `(!)`). We’re working to handle those situations better. - -For now, rerun your command with `--force`, or uninstall manually. - -**Do not open an issue.** diff --git a/doc/reporting_bugs/wrong_number_of_arguments_error.md b/doc/reporting_bugs/wrong_number_of_arguments_error.md new file mode 100644 index 0000000000000..610dd65724d02 --- /dev/null +++ b/doc/reporting_bugs/wrong_number_of_arguments_error.md @@ -0,0 +1,3 @@ +Make sure the issue really lies with your macOS version. To do so, try to install the software manually. If it is incompatible with your macOS version, it will tell you. In that case, there is nothing we can do to help you install the software, but we can add a [`depends_on macos:`](https://github.com/Homebrew/homebrew-cask/blob/master/doc/cask_language_reference/stanzas/depends_on.md#depends_on-macos) stanza to prevent the cask from trying to install on incompatible macOS versions. + +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. diff --git a/doc/reporting_bugs/wrong_number_of_arguments_fix.md b/doc/reporting_bugs/wrong_number_of_arguments_fix.md deleted file mode 100644 index 5b5b4d5ec5ba6..0000000000000 --- a/doc/reporting_bugs/wrong_number_of_arguments_fix.md +++ /dev/null @@ -1,5 +0,0 @@ -[Go back](a_cask_fails_to_install.md#wrong-number-of-arguments-error) - -Make sure the issue really lies with your macOS version. To do so, try to install the software manually. If it is incompatible with your macOS version, it will tell you. In that case, there is nothing we can do to help you install the software, but we can add a [`depends_on macos:`](https://github.com/Homebrew/homebrew-cask/blob/master/doc/cask_language_reference/stanzas/depends_on.md#depends_on-macos) stanza to prevent the cask from trying to install on incompatible macOS versions. - -Follow the instructions to [submit a fix](../../CONTRIBUTING.md#updating-a-cask), and make the change to the cask. If using `cask-repair`, you may give it the `--edit-cask` flag when calling it on the command-line to step right into editing it. If you’re having trouble submitting the fix or manually installing the software worked without a problem, [open an issue](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md) explaining your steps so far and the current situation.