From d80c1f8b8d4a958db8dd3483c4c3a401e82dba43 Mon Sep 17 00:00:00 2001 From: Mayur Pawashe Date: Sat, 21 Aug 2021 11:55:20 -0700 Subject: [PATCH] Add minor documentation changes (#80) * Fix programatic/programmatic typo * Refer to programmatic setup in upgrading section instead of recommending SPUUpdater * Update sparkle-cli usage * Update .gitignore to ignore Jekyll cache files --- .gitignore | 2 ++ documentation/index.md | 2 +- .../index.md | 0 documentation/publishing/index.md | 4 ++-- documentation/sparkle-cli/index.md | 8 +++++++- documentation/upgrading/index.md | 14 +++++++------- 6 files changed, 19 insertions(+), 11 deletions(-) rename documentation/{programatic-setup => programmatic-setup}/index.md (100%) diff --git a/.gitignore b/.gitignore index a4f98c1..53d5519 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,5 @@ _site .sass-cache vnu.jar .DS_Store +.jekyll-cache + diff --git a/documentation/index.md b/documentation/index.md index 9114b02..5120eb3 100644 --- a/documentation/index.md +++ b/documentation/index.md @@ -53,7 +53,7 @@ These instructions are for regular .app bundles. If you want to update a non-app If you are using Sparkle 2, `SUUpdater` is a deprecated stub. While it is still functional for transitional purposes, new applications will want to use `SPUStandardUpdaterController` in the above steps instead. -Sparkle can also be instantiated and [set up programmatically](/documentation/programatic-setup). +Sparkle can also be instantiated and [set up programmatically](/documentation/programmatic-setup). ### 3. Segue for security concerns diff --git a/documentation/programatic-setup/index.md b/documentation/programmatic-setup/index.md similarity index 100% rename from documentation/programatic-setup/index.md rename to documentation/programmatic-setup/index.md diff --git a/documentation/publishing/index.md b/documentation/publishing/index.md index 7d1dcfd..23b717e 100644 --- a/documentation/publishing/index.md +++ b/documentation/publishing/index.md @@ -264,11 +264,11 @@ Channels can only be used when all of your users downloading your appcast are ru ## Setting the feed programmatically -The appcast feed URL can be changed programatically at runtime. If the feed URL is always static and the same, please set it in the Info.plist with the `SUFeedURL` key instead. Even if you have a secondary appcast feed, we recommend keeping a default one specified in the application's Info.plist. +The appcast feed URL can be changed programmatically at runtime. If the feed URL is always static and the same, please set it in the Info.plist with the `SUFeedURL` key instead. Even if you have a secondary appcast feed, we recommend keeping a default one specified in the application's Info.plist. If you want to set the feed programmatically to provide beta/nightly updates, please try to adopt [channels](#channels) in the future instead. If you are supporting older Sparkle versions, continue reading on. -The recommended way to change the feed URL programatically is using `-[SUUpdaterDelegate feedURLStringForUpdater:]` (or `-[SPUUpdaterDelegate feedURLStringForUpdater:]` in Sparkle 2). +The recommended way to change the feed URL programmatically is using `-[SUUpdaterDelegate feedURLStringForUpdater:]` (or `-[SPUUpdaterDelegate feedURLStringForUpdater:]` in Sparkle 2). Here is an example: diff --git a/documentation/sparkle-cli/index.md b/documentation/sparkle-cli/index.md index 7ce3e1d..dfe63f9 100644 --- a/documentation/sparkle-cli/index.md +++ b/documentation/sparkle-cli/index.md @@ -13,7 +13,7 @@ Sparkle 2.0 includes a command line utility that can update Sparkle-based applic ``` ./sparkle.app/Contents/MacOS/sparkle -Usage: sparkle.app/Contents/MacOS/sparkle bundle [--application ] [--check-immediately] [--probe] [--grant-automatic-checks] [--send-profile] [--defer-install] [--interactive] [--verbose] +Usage: ./sparkle.app/Contents/MacOS/sparkle bundle [--application app-path] [--check-immediately] [--probe] [--channels chan1,chan2,…] [--feed-url feed-url] [--grant-automatic-checks] [--send-profile] [--defer-install] [--interactive] [--allow-major-upgrades] [--verbose] Description: Check if any new updates for a Sparkle supported bundle need to be installed. @@ -44,6 +44,12 @@ Options: --probe Probe for updates. Check if any updates are available but do not install. An exit status of 0 is returned if a new update is available. + --allow-major-upgrades + Allows probing and installing major upgrades. Without passing this, an exit + status of 2 is returned if a major upgrade is found. + --channels + List of allowed Sparkle channels to look for updates in. By default, + only the default channel is used. --feed-url URL for appcast feed. This URL will be used for the feed instead of the one in the bundle's Info.plist or in the bundle's user defaults. diff --git a/documentation/upgrading/index.md b/documentation/upgrading/index.md index b3c8bdc..c1a0125 100644 --- a/documentation/upgrading/index.md +++ b/documentation/upgrading/index.md @@ -17,21 +17,21 @@ The `SUUpdater` class has been deprecated and split up in Sparkle 2, but it is s Sparkle 2 includes three new classes / protocols: * **SPUUpdater** - The main API in Sparkle for controlling the update mechanism. * **SPUUserDriver** - The API in Sparkle for controlling the user interface & interaction (`SPUStandardUserDriver` is the standard one). -* **SPUStandardUpdaterController** - A controller class that instantiates a `SPUUpdater` using `SPUStandardUserDriver` in a nib and allows [binding UI](/documentation/preferences-ui#sparkle-2x-beta) to it. +* **SPUStandardUpdaterController** - A convenient controller class that instantiates a `SPUUpdater` targeting the main application bundle and uses Sparkle's standard user interface (`SPUStandardUserDriver`). This class can also be instantiated in a nib and allows [binding UI](/documentation/preferences-ui#sparkle-2x-beta) to it. If you were previously instantiating a `SUUpdater` in a nib, you will want to adopt `SPUStandardUpdaterController` as shown in the [basic setup](/documentation#2-set-up-a-sparkle-updater-object). -If you were previously instantiating a `SUUpdater` in code, you will want to adopt instantiating a `SPUUpdater`. +If you were previously instantiating a `SUUpdater` in code, please refer to the [programmatic setup guide](/documentation/programmatic-setup). -The deprecated `SUUpdater` in 2 is now a stub that uses both a `SPUUpdater` and `SPUStandardUserDriver`. +The deprecated `SUUpdater` in Sparkle 2 is now a stub that uses both a `SPUUpdater` and `SPUStandardUserDriver`. -If you create a `SPUUpdater` instance programatically, you are now able to create an updater that can update other Sparkle-based bundles and/or an updater that can use your own `SPUUserDriver` / user interface. [sparkle-cli](/documentation/sparkle-cli) makes use of both features as an example. +If you create a `SPUUpdater` instance directly, you can now create an updater that can update other Sparkle-based bundles and/or an updater that can use your own user interface (`SPUUserDriver`). [sparkle-cli](/documentation/sparkle-cli) makes use of both features as an example. -`SPUUpdater` and its delegate `SPUUpdaterDelegate` (unlike `SUUpdater`) do not contain any user-interface or AppKit logic. The UI bits were separated into classes implementing `SPUUserDriver` and its delegates. A developer writing their own updater user interface may choose to build Sparkle with `SPARKLE_BUILD_UI_BITS=0` which strips out the UI bits that Sparkle provides out of the box. +`SPUUpdater` and its delegate `SPUUpdaterDelegate` (unlike `SUUpdater`) do not contain any user-interface or AppKit logic. The UI bits were separated into classes implementing `SPUUserDriver` and its delegates. A developer writing their own updater user interface may choose to build Sparkle with `SPARKLE_BUILD_UI_BITS=0` which strips out the standard UI bits that Sparkle provides out of the box. `SPUUpdater` does not maintain singleton or global instances (unlike `SUUpdater`). Plug-ins that share the same process as their host should prefer to use an external tool like [sparkle-cli](/documentation/sparkle-cli) instead, rather than sharing or injecting a Sparkle.framework in its host. A bit more details about updating bundles [here](/documentation/bundles#sparkle-2x-beta). -Downgrades were poorly supported in Sparkle 1 and are now unavailable in Sparkle 2 (via `SPARKLE_AUTOMATED_DOWNGRADES`). +Downgrades were poorly supported in Sparkle 1 (via `SPARKLE_AUTOMATED_DOWNGRADES`) and are now unavailable in Sparkle 2. The behavior for the `-bestValidUpdateInAppcast:forUpdater:` delegate method on `SPUUpdaterDelegate` has changed. Please review its header documentation for more information. In short: * Delta updates cannot be returned. A top level item must be returned. @@ -56,7 +56,7 @@ Sparkle 2 supports [sandboxed applications](/documentation/sandboxing) via integ If you are migrating from earlier alpha versions of Sparkle 2, you may find that some of the XPC Services are now optional and re-signing the services may not be necessary. Please read the updated [sandboxing guide](/documentation/sandboxing) for more information. -If you use package (pkg) based updates, please see [Package Updates](/documentation/package-updates) for migration notes. In particular, your appcast items may need to include an appropriate installation type to help Sparkle decide if authorization is needed before starting the installer. +If you use package (pkg) based updates, please see [Package Updates](/documentation/package-updates) for migration notes. In particular, your appcast items may need to include an appropriate installation type to help Sparkle decide if authorization is needed before starting the installer. This is not needed for bare package updates. Sparkle 2 enhances support for [major upgrades](/documentation/publishing#Major-upgrades).