Merge pull request #3 from claui/vscode-shellcheck-0.21

Update README for vscode-shellcheck v0.21.2

README.md

@@ -35,19 +35,60 @@ Unlike `vsce package`, running `yarn package` will work around issue [microsoft/
 Use `yarn package` as long as the issue is unresolved.
 
 ## Publishing the extension
-To publish to the VS Code Extension Marketplace, first choose a target version.  
-[The VS Code folks recommend](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#prerelease-extensions) the following numbering scheme:
+
+Publishing the extension has several steps:
+
+1. Merge the contributions.
+2. Choose a target version number.
+3. Publish to the Marketplace. (This modifies `extension/package.json`.)
+4. Create a Git commit, Git tag, GitHub prerelease and GitHub PR.
+
+### Merging the contributions
+
+Make sure that all the contributions you’re going to have in the
+release have been merged to the `main` branch.
+
+### Choosing a target version number
+
+With all contributions merged into `main`, choose a target version
+number.  
+[The VS Code folks recommend](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#prerelease-extensions)
+the following numbering scheme:
 
 - `major.ODD_NUMBER.patch` (e.g. 1.1.0) for **pre-release** versions; and
 - `major.EVEN_NUMBER.patch` (e.g. 1.2.0) for **release** versions.
 
+### Publishing to the Marketplace
+
 After deciding on a target version, run:
 
+- `git checkout main`
 - `yarn login`
 - `yarn publish [--pre-release] [version]`
 
 The `yarn publish` command first updates the version number in [extension/package.json](./extension/package.json) to the given version. Then it packages and publishes the extension to the VS Code Extension Marketplace.
 
+### Committing, tagging and creating a GitHub prerelease and PR
+
+With the extension now published on the Marketplace, commit the
+change, create a tag, push, cut a GitHub (pre-)release, and create a
+pull request against `main`:
+
+```
+(
+  set -eux
+  git checkout -b publish
+  tag="$(jq -r '"v" + .version' extension/package.json)"
+  echo "New tag: ${tag}"
+  git add -u
+  git commit --edit -m "Release ${tag}"
+  git tag "${tag}"
+  git push --tags
+  gh release --generate-notes --prerelease "${tag}"
+  gh pr create --fill --web
+)
+```
+
 ## Maintenance
 
 ### yarn install

extension/README.md

@@ -6,6 +6,13 @@ package repositories.
 It currently supports only a single type of package repository: the
 [Arch User Repository](https://aur.archlinux.org/) (AUR).
 
+## Screenshots
+
+| `PKGBUILD` file without this extension | `PKGBUILD` file with this extension |
+|:--------------------------------------:|:-----------------------------------:|
+| <img alt="Screenshot of a PKGBUILD file opened in VS Code without the Packaging extension installed. The screenshot shows dozens of ShellCheck diagnostics, most of which are useless for PKGBUILDs. The two relevant findings are difficult to spot because they have become lost in the noise." src="https://raw.githubusercontent.com/claui/vscode-packaging/main/extension/images/screenshot-pkgbuild-without-extension.png" width="75%"> | <img alt="Screenshot of a PKGBUILD file opened in VS Code with the Packaging extension installed. The screenshot now only shows the two ShellCheck findings which are actual mistakes in the PKGBUILD." src="https://raw.githubusercontent.com/claui/vscode-packaging/main/extension/images/screenshot-pkgbuild-with-extension.png" width="75%"> |
+| [ShellCheck](https://marketplace.visualstudio.com/items?itemName=timonwong.shellcheck) findings are mostly irrelevant. | Only see ShellCheck diagnostics that matter. |
+
 ## Features
 
 ### PKGBUILD (AUR)
@@ -37,19 +44,16 @@ extension in the following ways:
 
 - Will not affect regular shell scripts, only `PKGBUILD`s
 
-## Caveat
+## Prerequisites
 
-This extension is work in progress. It requires a custom
-build of the ShellCheck extension at this time.  
-Specifically, it won’t work with the ShellCheck extension version
-0.21.1 or older.
+This extension depends on the
+[ShellCheck extension](https://marketplace.visualstudio.com/items?itemName=timonwong.shellcheck),
+maintained by Felipe Santos.
 
-If you want to use this extension, you can either
-[package it
-yourself](https://github.com/claui/vscode-packaging/blob/main/README.md#building-the-extension)
-or wait for
-[the first release](https://github.com/claui/vscode-packaging/milestone/1)
-to be published on the VS Code Marketplace.
+Usually, VS Code will take care of this dependency for you.
+When in doubt, you can reinstall the ShellCheck extension to get the
+latest version. You should have to do that only once though, if
+ever.
 
 ## FAQ