Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: update release docs #232

Merged
merged 1 commit into from
Mar 28, 2024
Merged

feat: update release docs #232

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 0 additions & 14 deletions docs/esm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
40 changes: 28 additions & 12 deletions docs/releasing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand All @@ -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": {
Expand All @@ -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.
Expand Down