Merge pull request #662 from rgoldberg/661-github

Improve GitHub web pages
mas-cli · Dec 1, 2024 · 463567b · 463567b
2 parents 5a198f7 + 2357dae
commit 463567b
Show file tree

Hide file tree

Showing 3 changed files with 104 additions and 33 deletions.
diff --git a/.github/ISSUE_TEMPLATE/01-bug-report.yml b/.github/ISSUE_TEMPLATE/01-bug-report.yml
@@ -1,30 +1,64 @@
 ---
 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
     id: macos-version
     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
     id: macos-build
     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,28 +95,35 @@ 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
     id: reproduction
     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
@@ -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
@@ -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 <search-term>` 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 <app-id>` 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 <app-id>…` 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 <search-term>` installs the first result that would be returned by `mas search <search-term>`.
 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 <apple-id>` 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
 ```