Merge pull request #232 from oclif/mdonnalley/release-docs

feat: update release docs
oclif · Mar 28, 2024 · 9215458 · 9215458
2 parents dea74d1 + a30b3c7
commit 9215458
Show file tree

Hide file tree

Showing 2 changed files with 28 additions and 26 deletions.
diff --git a/docs/esm.md b/docs/esm.md
@@ -4,20 +4,6 @@ title: ESM
 
 Version 3.0.0 of `@oclif/core` officially supports ESM plugin development and CJS/ESM interoperability, meaning that you can have a root plugin written with CJS and your plugins written in ESM or vice versa.
 
-- [Interoperability Overview](#interoperability-overview)
-  - [ESM Root plugin](#esm-root-plugin)
-  - [CJS Root plugin](#cjs-root-plugin)
-- [Creating an ESM plugin](#creating-an-esm-plugin)
-- [Migrating a CJS plugin to ESM](#migrating-a-cjs-plugin-to-esm)
-  - [Update bin scripts](#update-bin-scripts)
-    - [bin/dev → bin/dev.js](#bindev--bindevjs)
-    - [bin/run → bin/run.js](#binrun--binrunjs)
-  - [Update tsconfig.json](#update-tsconfigjson)
-  - [Update package.json to "module" type](#update-packagejson-to-module-type)
-  - [Update references to bin scripts](#update-references-to-bin-scripts)
-  - [Update mocharc settings](#update-mocharc-settings)
-
-
 ## Interoperability Overview
 
 Here's a high level overview of ESM/CJS interoperability:

diff --git a/docs/releasing.md b/docs/releasing.md
@@ -49,13 +49,30 @@ In the Heroku CLI, we have it automatically build and release the beta channel o
 
 Build a windows installer with `oclif pack win`. It will build into `./dist/win`. This can be uploaded to S3 with `oclif upload win` and promoted within S3 with `oclif promote --win`.
 
-The installer uses 7zip and nsis.  If you're in a mac or unix environment and don't have them, you can use homebrew to insall them.
+`oclif pack win` depends on having 7zip and nsis installed. If you're in a mac or unix environment and don't have them, you can use homebrew to install them.
 
 ```sh
 brew install nsis
 brew install p7zip
 ```
 
+### Signing the installer
+
+To produce a signed installer you need to set the scoped `<CLI>_WINDOWS_SIGNING_PASS` env var (e.g. `MY_CLI_WINDOWS_SIGNING_PASS`) and set `windows.name` and `windows.keypath` in your package.json:
+
+```json
+{
+  "oclif": {
+    "windows": {
+      "name": "My CLI",
+      "keypath": "path/to/private.key"
+    }
+  }
+}
+```
+
+Refer to [Microsoft's documentation](https://learn.microsoft.com/en-us/windows/win32/msi/authoring-a-fully-verified-signed-installation) on how to acquire a verified digital signature for your CLI.
+
 ## macOS installer
 
 Build a macOS .pkg installer with `oclif pack macos`. It will build into `./dist/macos`. This can be uploaded to S3 with `oclif upload macos` and promoted within S3 with `oclif promote --macos`. You need to set the macOS identifier at `oclif.macos.identifier` in `package.json` (we use "com.heroku.cli" and "com.salesforce.cli" as the identifiers for the Heroku CLI and the Salesforce CLI, respectively).
@@ -66,8 +83,9 @@ The upload command defaults to using the ACL setting `public-read` unless anothe
 
 To address this, consider updating the oclif section of your package.json with the desired ACL setting. The example below demonstrates how to set the acl to bucket-owner-full-control:
 
-```
-"oclif": {
+```json
+{
+  "oclif": {
     "bin": "myOclifApp",
     "dirname": "myOclifApp-cli-data",
     "update": {
@@ -79,30 +97,28 @@ To address this, consider updating the oclif section of your package.json with t
     },
     "macos": {
       "identifier": "com.myOclifApp.cli"
-    },
-
-...
-
+    }
+  }
 }
 ```
 
 Amazon has a userguide [here](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ensure-object-ownership.html#ensure-object-ownership-bucket-policy) for help how to configure Bucket Policy settings.
 
 ### Signing the installer
 
-To be able to sign an "installer signing identity" has to be available on the build machine (read more on certificates [here](https://developer.apple.com/help/account/create-certificates/certificates-overview)).  
-Make sure such a certificate is created in developer.apple.com and that the certificate is downloaded and installed in the KeyChain of the build machine.  
-The certificate name has to be specified in the `oclif.macos.sign` in `package.json`.  
+To be able to sign an "installer signing identity" has to be available on the build machine (read more on certificates [here](https://developer.apple.com/help/account/create-certificates/certificates-overview)).
+Make sure such a certificate is created in developer.apple.com and that the certificate is downloaded and installed in the KeyChain of the build machine.
+The certificate name has to be specified in the `oclif.macos.sign` in `package.json`.
 
-Example: 
+Example:
 ```
     "macos": {
       "identifier": "com.myOclifApp",
       "sign": "\"3rd Party Mac Developer Installer: myOclifCompany (R2315646)\""
     },
 ```
 
-Pay attention to the escaped quotation marks, the certificate name is passed on as an argument to the `pkgbuild` command so without quotation marks it might break.  
+Pay attention to the escaped quotation marks, the certificate name is passed on as an argument to the `pkgbuild` command so without quotation marks it might break.
 For the Heroku CLI the certificate name is "Developer ID Installer: Heroku INC". And optionally set the keychain with `OSX_KEYCHAIN`.
 
 Installed certificates on the build machine can be viewed in the Keychain Access app.