From 1dea9705127932db033b4ba48d77789d1ac64823 Mon Sep 17 00:00:00 2001 From: Zorg Date: Sun, 19 Sep 2021 08:44:01 -0700 Subject: [PATCH] Update changelog and documentation (#1956) * Update author to Sparkle Project when generating documentation * Sync change log from 1.27.0 * Add recommendation to not call checkForUpdatesInBackground directly * Add testing documentation for latsUpdateCheckDate * Fix formatting with user driver header documentation --- CHANGELOG | 2 ++ .../SUInstallerLauncher+Private.h | 2 +- Makefile | 2 +- Sparkle/SPUUpdater.h | 10 +++++- Sparkle/SPUUserDriver.h | 35 +++++++++++-------- 5 files changed, 33 insertions(+), 18 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index 7d6d87d9a3..e8e4963ea1 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -54,6 +54,8 @@ If you are migrating from earlier alpha versions of Sparkle 2, please re-familia * Fix appcast pubDate tag generation in different locales from #1898 (Sungbin Jo) * Create valid xar archives for generating binary delta files from #1906 (Zorg) * Fix a few issues with German localization from #1931 (J-rg) + * Fix issues with Russian localizations from #1947 (Konstantin Zamyakin) + * Fix issues with Czech localizations from #1943 (Vojtěch Koňařík) * Add an automated workflow that builds and publishes official Sparkle releases (Tony Arnold, Zorg) # 1.26.0 diff --git a/InstallerLauncher/SUInstallerLauncher+Private.h b/InstallerLauncher/SUInstallerLauncher+Private.h index 07ecb3d618..f8e0410c5d 100644 --- a/InstallerLauncher/SUInstallerLauncher+Private.h +++ b/InstallerLauncher/SUInstallerLauncher+Private.h @@ -22,7 +22,7 @@ This API is not supported when used directly from a Sandboxed applications and will always return @c YES in that case. @param bundlePath The bundle path to test if authorization is needed when performing an update that replaces this bundle. - @return @c YES if Sparkle thinks authorization is needed to update the @p bundlePath, otherwise @c NO. + @return @c YES if Sparkle thinks authorization is needed to update the @c bundlePath, otherwise @c NO. */ SU_EXPORT BOOL SPUSystemNeedsAuthorizationAccessForBundlePath(NSString *bundlePath); diff --git a/Makefile b/Makefile index 4ac8709ff0..28d521fd67 100644 --- a/Makefile +++ b/Makefile @@ -25,7 +25,7 @@ build: # Need to first gem install jazzy to run this rule docs: - jazzy --objc --umbrella-header Sparkle/Sparkle.h --framework-root . --readme Documentation/API_README.markdown --theme jony --output Documentation/html + jazzy --author "Sparkle Project" --objc --umbrella-header Sparkle/Sparkle.h --framework-root . --readme Documentation/API_README.markdown --theme jony --output Documentation/html uitest: xcodebuild -scheme UITests -configuration Debug test diff --git a/Sparkle/SPUUpdater.h b/Sparkle/SPUUpdater.h index 000a736cde..e8f71aedbb 100644 --- a/Sparkle/SPUUpdater.h +++ b/Sparkle/SPUUpdater.h @@ -104,6 +104,10 @@ SU_EXPORT @interface SPUUpdater : NSObject /** Checks for updates, but does not display any UI unless an update is found. + You usually do not need to call this method directly. If `automaticallyChecksForUpdates` is @c YES, + Sparkle calls this method automatically according to its update schedule using the `updateCheckInterval` + and the `lastUpdateCheckDate`. + This is meant for programmatically initating a check for updates. That is, it will display no UI unless it finds an update, in which case it proceeds as usual. This will not find updates that the user has opted into skipping. @@ -166,7 +170,7 @@ SU_EXPORT @interface SPUUpdater : NSObject A property indicating whether or not to check for updates automatically. By default, Sparkle asks users on second launch for permission if they want automatic update checks enabled - and sets this property based on their response. If SUEnableAutomaticChecks is set in the Info.plist, + and sets this property based on their response. If `SUEnableAutomaticChecks` is set in the Info.plist, this permission request is not performed however. Setting this property will persist in the host bundle's user defaults. @@ -263,6 +267,10 @@ SU_EXPORT @interface SPUUpdater : NSObject /** The date of the last update check or nil if no check has been performed yet. + + For testing purposes, the last update check is stored in the `SULastCheckTime` key in the host bundle's user defaults. + For example, `defaults delete my-bundle-id SULastCheckTime` can be invoked to clear the last update check time and test + if update checks are automatically scheduled. */ @property (nonatomic, readonly, copy, nullable) NSDate *lastUpdateCheckDate; diff --git a/Sparkle/SPUUserDriver.h b/Sparkle/SPUUserDriver.h index 05fe9cbc6f..c5189e4e85 100644 --- a/Sparkle/SPUUserDriver.h +++ b/Sparkle/SPUUserDriver.h @@ -58,17 +58,17 @@ SU_EXPORT @protocol SPUUserDriver * Let the user know a new update is found and ask them what they want to do. * Before this point, `-showUserInitiatedUpdateCheckWithCancellation:` may be called. * - * @param appcastItem The Appcast Item containing information that reflects the new update. + * The potential `stage`s on the updater @c state are: * - * @param state The current state of the user update. - * The state.stage values are: * `SPUUpdateStateNotDownloaded` - Update has not been downloaded yet. + * * `SPUUpdateStateDownloaded` - Update has already been downloaded but not started installing yet. + * * `SPUUpdateStateInstalling` - Update has been downloaded and already started installing. * - * state.userInitiated indicates if the update was initiated by the user or if it was automatically scheduled in the background. + * The `userIntiated` property on the @c state indicates if the update was initiated by the user or if it was automatically scheduled in the background. * - * Additionally, these properties on the appcastItem are of importance: + * Additionally, these properties on the @c appcastItem are of importance: * * @c appcastItem.informationOnlyUpdate indicates if the update is only informational and should not be downloaded. You can direct the user to the infoURL property of the appcastItem in their web browser. Sometimes information only updates are used as a fallback in case a bad update is shipped, so you'll want to support this case. * @@ -76,9 +76,9 @@ SU_EXPORT @protocol SPUUserDriver * * @c appcastItem.criticalUpdate indicates if the update is a critical update. * - * @param reply * A reply of `SPUUserUpdateChoiceInstall` begins or resumes downloading or installing the update. - * If the state.stage is `SPUUserUpdateStateInstalling`, this may send a quit event to the application and relaunch it immediately (in this state, this behaves as a fast "install and Relaunch"). Do not use this reply if @c appcastItem.informationOnlyUpdate is YES. + * If the state.stage is `SPUUserUpdateStateInstalling`, this may send a quit event to the application and relaunch it immediately (in this state, this behaves as a fast "install and Relaunch"). + * Do not use this reply if @c appcastItem.informationOnlyUpdate is YES. * * A reply of `SPUUserUpdateChoiceDismiss` dismisses the update for the time being. The user may be reminded of the update at a later point. * If the state.stage is `SPUUserUpdateStateDownloaded`, the downloaded update is kept after dismissing until the next time an update is shown to the user. @@ -87,6 +87,10 @@ SU_EXPORT @protocol SPUUserDriver * A reply of `SPUUserUpdateChoiceSkip` skips this particular version and won't notify the user again, unless they initiate an update check themselves. * If @c appcastItem.majorUpgrade is YES, the major update and any future minor updates to that major release are skipped. * If the state.stage is `SPUUpdateStateInstalling`, the installation is also canceled when the update is skipped. + * + * @param appcastItem The Appcast Item containing information that reflects the new update. + * @param state The current state of the user update. See above discussion for notable properties. + * @param reply The reply which indicates if the update should be installed, dismissed, or skipped. See above discussion for more details. */ - (void)showUpdateFoundWithAppcastItem:(SUAppcastItem *)appcastItem state:(SPUUserUpdateState *)state reply:(void (^)(SPUUserUpdateChoice))reply; @@ -118,17 +122,17 @@ SU_EXPORT @protocol SPUUserDriver * Let the user know a new update was not found after they tried initiating an update check. * Before this point, `-showUserInitiatedUpdateCheckWithCancellation:` may be called. * - * @param error The error associated with why a new update was not found. - * There are various reasons a new update is unavailable and can't be installed. - * This error object is populated with recovery and suggestion strings suitable to be shown in an alert. + * There are various reasons a new update is unavailable and can't be installed. + * The @c error object is populated with recovery and suggestion strings suitable to be shown in an alert. * - * The userInfo dictionary is also populated with two keys: + * The @c userInfo dictionary on the @c error is also populated with two keys: * - * `SPULatestAppcastItemFoundKey`: if available, this may provide the latest SUAppcastItem that was found. + * `SPULatestAppcastItemFoundKey`: if available, this may provide the latest SUAppcastItem that was found. * - * `SPUNoUpdateFoundReasonKey`: if available, this will provide the `SUNoUpdateFoundReason`. For example the reason could be because - * the latest version in the feed requires a newer OS version or could be because the user is already on the latest version. + * `SPUNoUpdateFoundReasonKey`: if available, this will provide the `SUNoUpdateFoundReason`. For example the reason could be because + * the latest version in the feed requires a newer OS version or could be because the user is already on the latest version. * + * @param error The error associated with why a new update was not found. See above discussion for more details. * @param acknowledgement Acknowledge to the updater that no update found error was shown. */ - (void)showUpdateNotFoundWithError:(NSError *)error acknowledgement:(void (^)(void))acknowledgement; @@ -208,7 +212,6 @@ SU_EXPORT @protocol SPUUserDriver * Let the user know that the update is ready to install and relaunch, and ask them whether they want to proceed. * Note if the target application has already terminated, this method may not be invoked. * - * @param reply * A reply of `SPUUserUpdateChoiceInstall` installs the update the new update immediately. The application is relaunched only if it is still running by the time this reply is invoked. If the application terminates on its own, Sparkle will attempt to automatically install the update. * * A reply of `SPUUserUpdateChoiceDismiss` dismisses the update installation for the time being. Note the update may still be installed automatically after the application terminates. @@ -216,6 +219,8 @@ SU_EXPORT @protocol SPUUserDriver * A reply of `SPUUserUpdateChoiceSkip` cancels the current update that has begun installing and dismisses the update. In this circumstance, the update is canceled but this update version is not skipped in the future. * * Before this point, `-showInstallingUpdate` will be called. + * + * @param reply The reply which indicates if the update should be installed, dismissed, or skipped. See above discussion for more details. */ - (void)showReadyToInstallAndRelaunch:(void (^)(SPUUserUpdateChoice))reply;