diff --git a/.github/ISSUE_TEMPLATE/01-bug-report.yml b/.github/ISSUE_TEMPLATE/01-bug-report.yml index 663539312..a4a7cfc5a 100644 --- a/.github/ISSUE_TEMPLATE/01-bug-report.yml +++ b/.github/ISSUE_TEMPLATE/01-bug-report.yml @@ -1,14 +1,40 @@ --- name: Bug Report description: Report a bug. -labels: "\U0001F41B bug" +labels: ["\U0001F41B bug"] body: + - type: markdown + attributes: + value: | + # Console command & output formatting + + When providing commands & output, please use the following format (where `…` is a placeholder): + + - Use a multiline console block: start with ```` ```console ````, end with ```` ``` ````, each on its own line + - Prefix each non-console step (or comment) with two hashes & a space: `## …` + - Remove shell prompts; instead, prefix each console command with a dollar sign & a space: `$ …` + - Prefix each output line beginning with `#`, `$`, `%`, or `>` with an additional instance of that character: `##…`, `$$…`, `%%…`, or `>>…` + - Write all other output lines without any prefix: `…` + + e.g.: + + ````text + ```console + ## In the Mac App Store GUI, … + $ mas list + 123 App 1 (4.5.6) + 124 App 2 (10.2) + ``` + ```` + + # Environment - type: input id: mas-version attributes: label: mas version description: The output of `mas version` - placeholder: ex. 1.8.7 + placeholder: "example: 1.8.7" validations: required: true - type: input @@ -16,7 +42,7 @@ body: attributes: label: macOS version description: The output of `sw_vers -productVersion` - placeholder: ex. 15.1.1 + placeholder: "example: 15.1.1" validations: required: true - type: input @@ -24,7 +50,15 @@ body: attributes: label: macOS build version description: The output of `sw_vers -buildVersion` - placeholder: ex. 24B2091 + placeholder: "example: 24B2091" + validations: + required: true + - type: input + id: processor + attributes: + label: Processor + description: The output of `sysctl -n machdep.cpu.brand_string` + placeholder: "example: Apple M1" validations: required: true - type: dropdown @@ -61,18 +95,24 @@ body: # yamllint enable rule:trailing-spaces validations: required: false + - type: markdown + attributes: + value: | + # Issue - type: textarea id: expected-behavior attributes: label: Expected behavior - placeholder: Prefer copied & pasted commands & output instead of screenshots + placeholder: Prefer copied, pasted & formatted commands & output in a multiline console block (as instructed + above) instead of screenshots validations: required: true - type: textarea id: actual-behavior attributes: label: Actual behavior - placeholder: Prefer copied & pasted commands & output instead of screenshots + placeholder: Prefer copied, pasted & formatted commands & output in a multiline console block (as instructed + above) instead of screenshots validations: required: true - type: textarea @@ -80,9 +120,10 @@ body: attributes: label: Steps to reproduce description: | - Provide commands to reproduce the bug in the multiline shell block. Write non-shell steps as comments (`# …`). + Copy, paste & format commands & output in the multiline console block (as instructed above) that reproduce the bug value: | - ```shell + ```console ``` validations: @@ -91,6 +132,6 @@ body: id: context attributes: label: Additional context - placeholder: ex. Does the bug occur in other mas or macOS versions? + placeholder: "example: Does the bug occur in other mas or macOS versions?" validations: required: false diff --git a/.github/ISSUE_TEMPLATE/02-feature-request.yml b/.github/ISSUE_TEMPLATE/02-feature-request.yml index f9132a094..d3e57e794 100644 --- a/.github/ISSUE_TEMPLATE/02-feature-request.yml +++ b/.github/ISSUE_TEMPLATE/02-feature-request.yml @@ -1,33 +1,63 @@ --- -name: Feature request +name: Feature Request description: Request a feature. -labels: "\U0001F195 feature request" +labels: ["\U0001F195 feature request"] body: + - type: markdown + attributes: + value: | + # Console command & output formatting + + When providing commands & output, please use the following format (where `…` is a placeholder): + + - Use a multiline console block: start with ```` ```console ````, end with ```` ``` ````, each on its own line + - Prefix each non-console step (or comment) with two hashes & a space: `## …` + - Remove shell prompts; instead, prefix each console command with a dollar sign & a space: `$ …` + - Prefix each output line beginning with `#`, `$`, `%`, or `>` with an additional instance of that character: `##…`, `$$…`, `%%…`, or `>>…` + - Write all other output lines without any prefix: `…` + + e.g.: + + ````text + ```console + ## In the Mac App Store GUI, … + $ mas list + 123 App 1 (4.5.6) + 124 App 2 (10.2) + ``` + ```` + + # Feature - type: textarea id: problems attributes: label: Problem(s) addressed - placeholder: Prefer copied & pasted commands & output instead of screenshots + placeholder: Prefer copied, pasted & formatted commands & output in a multiline console block (as instructed + above) instead of screenshots validations: required: true - type: textarea id: proposals attributes: label: Proposed solution(s) - placeholder: Prefer copied & pasted commands & output instead of screenshots + placeholder: Prefer copied, pasted & formatted commands & output in a multiline console block (as instructed + above) instead of screenshots validations: required: true - type: textarea id: alternatives attributes: label: Alternative solution(s) - placeholder: Prefer copied & pasted commands & output instead of screenshots + placeholder: Prefer copied, pasted & formatted commands & output in a multiline console block (as instructed + above) instead of screenshots validations: required: false - type: textarea id: context attributes: label: Additional context - placeholder: Prefer copied & pasted commands & output instead of screenshots + placeholder: Prefer copied, pasted & formatted commands & output in a multiline console block (as instructed + above) instead of screenshots validations: required: false diff --git a/README.md b/README.md index 96b0ebffe..bde16720e 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ A command-line interface for the Mac App Store. Designed for scripting and autom [Homebrew](http://brew.sh) is the preferred way to install: -```bash +```shell brew install mas ``` @@ -30,7 +30,7 @@ brew install mas [MacPorts](https://www.macports.org/install.php) is an alternative way to install: -```bash +```shell sudo port install mas ``` @@ -46,7 +46,7 @@ for macOS 10.13+ (High Sierra or newer). To install mas from our tap: -```bash +```shell brew install mas-cli/tap/mas ``` @@ -93,7 +93,7 @@ neither for your macOS user, nor in the Mac App Store. `mas search ` searches by name for applications available from the Mac App Store. Providing the `--price` flag includes each app's price in the output. -```bash +```console $ mas search Xcode 497799835 Xcode 688199928 Docs for Xcode @@ -105,7 +105,7 @@ $ mas search Xcode `mas info ` displays more detailed information about an application available from the Mac App Store. -```bash +```console $ mas info 497799835 Xcode 16.0 [0.0] By: Apple Inc. @@ -123,7 +123,7 @@ All the commands in this section require you to be logged into an Apple ID for y `mas list` displays all the applications on your Mac that were installed from the Mac App Store. -```bash +```console $ mas list 497799835 Xcode (15.4) 640199958 Developer (10.6.5) @@ -134,7 +134,7 @@ $ mas list `mas outdated` displays all applications installed from the Mac App Store on your computer that have pending upgrades. -```bash +```console $ mas outdated 497799835 Xcode (15.4 -> 16.0) 640199958 Developer (10.6.5 -> 10.6.6) @@ -156,7 +156,7 @@ All the commands in this section require you to be logged into an Apple ID in th > `purchase` is currently a misnomer, because it currently can only "purchase" free > apps. To purchase apps that cost money, please purchase them directly in the Mac App Store. -```bash +```console $ mas purchase 497799835 ==> Downloading Xcode ==> Installed Xcode @@ -167,7 +167,7 @@ $ mas purchase 497799835 `mas install …` installs apps that you have already gotten/"purchased" from the Mac App Store. Providing the `--force` flag re-installs the app even if it is already installed on your computer. -```bash +```console $ mas install 497799835 ==> Downloading Xcode ==> Installed Xcode @@ -178,7 +178,7 @@ $ mas install 497799835 `mas lucky ` installs the first result that would be returned by `mas search `. Like `mas install`, `mas lucky` can only install apps that have previously been gotten/"purchased". -```bash +```console $ mas lucky Xcode ==> Downloading Xcode ==> Installed Xcode @@ -195,7 +195,7 @@ Use [`softwareupdate(8)`] to install system updates (e.g., Xcode Command Line To `mas upgrade` upgrades outdated apps installed from the Mac App Store. Without any arguments, it upgrades all such apps. -```bash +```console $ mas upgrade Upgrading 2 outdated applications: Xcode (15.4) -> (16.0) @@ -208,7 +208,7 @@ Developer (10.6.5) -> (10.6.6) Upgrades can be performed selectively by providing app IDs to `mas upgrade`. -```bash +```console $ mas upgrade 715768417 Upgrading 1 outdated application: Xcode (15.4) -> (16.0) @@ -228,20 +228,20 @@ These commands do not interact with the Apple ID for which your macOS user is si On macOS 10.12 (Sierra) or older, `mas signin ` signs in to the specified Apple ID in the Mac App Store. -```bash +```console $ mas signin mas@example.com Password: ``` Providing the `--dialog` flag signs in using a graphical dialog provided by Mac App Store. -```bash +```shell mas signin --dialog mas@example.com ``` You can also embed your password in the command. -```bash +```shell mas signin mas@example.com MyPassword ``` @@ -299,7 +299,7 @@ fix pasteboard behaviour which also works for mas. You should consider configuring `tmux` to use the wrapper but if you do not wish to do this it can be used on a one-off basis as follows: -```bash +```shell brew install reattach-to-user-namespace reattach-to-user-namespace mas install ``` @@ -319,7 +319,7 @@ All feedback is much appreciated! ✨ You can build from Xcode by opening the root mas directory, or from the Terminal: -```bash +```shell script/bootstrap script/build ``` @@ -333,7 +333,7 @@ Since Xcode does not officially support tests for command-line tool targets, all logic is part of the mas target with tests in masTests. Tests are written using [Quick]. -```bash +```shell script/test ```