Update documentation for 2.7.0 beta

documentation/customization/index.md

@@ -19,6 +19,7 @@ Here are the main routes by which you can bend Sparkle's behavior to your will:
 | `SUScheduledCheckInterval` | Number | The number of seconds between updates. The default is `86400` (1 day). Setting to 0 disables updates.<br /><br />**Note:** this has a minimum bound of 1 hour in order to keep you from accidentally overloading your servers. |
 | `SUAllowsAutomaticUpdates` | Boolean | By default, Sparkle automatically presents your users with the *option* to allow to automatically download and install any available updates if automatic checking of updates is enabled.<br/>Set this to `NO` to disallow automatic updates and require manual installation every time.<br/>Set this to `YES` to always allow automatic updates even if automatic checking of updates is disabled. |
 | `SUAutomaticallyUpdate` | Boolean | Default: `NO`. Enables automatic download and installation of updates by default. If set to `YES`, Sparkle will attempt to download and install new updates silently in the background. In Sparkle 1, updates won't be opted into this if users need to provide authorization. In Sparkle 2, updates will be downloaded but not installed automatically if authorization is required. In all versions of Sparkle, if the application hasn't quit for 1 week the user will be presented with installing the downloaded update (unless the updater delegate overrides this).<br/>This default property can later be overridden by setting [automaticallyDownloadsUpdates](/documentation/api-reference/Classes/SPUUpdater.html#/c:objc(cs)SPUUpdater(py)automaticallyDownloadsUpdates) in response to user setting changes.
+| `SUVerifyUpdateBeforeExtraction` | Boolean | Default: `NO`. Set this to `YES` to force verification of updates before Sparkle extracts the downloaded update. Use this setting if you want stronger update validation and you aren't likely to lose access to your private EdDSA key (typically stored inside the macOS Keychain). EdDSA signing is required to use this setting. [Key rotation](/documentation/#rotating-signing-keys) is still possible by using Apple Developer ID code signed disk images as fallback. This setting is available in Sparkle 2.7 (beta) and later. |
 | `SUShowReleaseNotes` | Boolean | Default: `YES`. Set this to `NO` to hide release notes display from the update alert. |
 | `SUAllowedURLSchemes` | Array of Strings | An array of custom URL schemes allowed to be clicked from Sparkle's release notes view. By default, Sparkle only allows clicks to links that have a safe known URL scheme (like `https`). This setting is available in Sparkle 2.5 and later.
 | `SUBundleName` | String | Optional alternative bundle display name. For example, if your bundle name already has a version number appended to it, setting this may help smooth out certain messages, e.g. "MyApp 3 4.0 is now available" vs "MyApp 4.0 is now available". |

documentation/delta-updates/index.md

@@ -11,10 +11,6 @@ For each new version you release, you can provide a list of `.delta` files in ad
 
 If the user is running a version of the app for which you haven't provided a `.delta`, or if the patch doesn't apply cleanly, they'll use the non-delta "full" update.
 
-<div class="alert alert-warning" role="alert">
-<strong>Note:</strong> Due to a macOS change, new delta patches must be created using generate_appcast or BinaryDelta from a Sparkle 1.27.0 or later distribution. Note that newly generated patches are still backwards compatible and can be patched from applications using versions of Sparkle framework older than 1.27.0.
-</div>
-
 ### Automated generation
 
 The `./bin/generate_appcast` tool that comes with Sparkle [automatically generates and signs delta updates](/documentation/#5-publish-your-appcast).
@@ -73,11 +69,12 @@ When you create a delta update between two versions of your application, you mus
 
 | Delta Format   | Supports                      | Changes                                                                                        |
 | --------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------- |
+| 4               | Sparkle 2.7 (beta)            | Preserves bundle creation date, more efficient hash verification. |
 | 3               | Sparkle 2.1                   | More efficient custom delta container format, lzma compression + other compression options, file rename heuristic tracking. |
 | 2               | Sparkle 1.10                  | Improved and changed hash function for reducing collisions.                                          |
 | 1               | Sparkle 1.5                   | Added initial binary delta format using libxar and bzip2 compression. Tracking of insertions, deletions, and binary file diffs using bsdiff. |
 
-Note if you are using `generate_appcast`, picking the delta version to use is automatically handled. If you are using `BinaryDelta create` though, you will need to pass the appropriate delta version via the `--version` argument.
+Note if you are using `generate_appcast`, picking the delta version to use is automatically handled. If you are manually using `BinaryDelta create` though, you will need to pass the appropriate delta version via the `--version` argument.
 
 Older delta format versions will eventually be phased out. Please do not create new patches using an older version than necessary. Always use the latest tools when creating delta patches because they may contain minor bug fixes that don't require a major format change.
 
@@ -105,6 +102,8 @@ Binary delta updates will pass but ignore or warn about the following metadata:
 * File permissions on symbolic links that are not `0755` are ignored, and `0755` will always be used instead. A warning will be issued. Some filesystems, e.g. Linux ones, do not support file permissions on symbolic links.
 * Irregular file permissions on files that are not `0755` or `0644` will be respected, but a warning may be issued (from Sparkle 2.1 onwards).
 * Custom icons users set using a resource fork (e.g. using Finder's `Get Info` window) are ignored/preserved when applying patches, but prohibited when creating patches (from Sparkle 2.2 onwards).
+* File modification dates are ignored and not preserved (but modification dates for the app bundle and embedded mdimporter bundles are later updated during installation)
+* File creation dates are ignored and not preserved inside the app bundle (but the creation date for the outer app bundle is preserved in the version 4 format).
 
 Binary delta updates do support the following meta changes:
 

documentation/index.md

@@ -93,7 +93,7 @@ Because Sparkle is downloading executable code to your users' systems, you must
     * Updates using [Installer package](/documentation/package-updates/) (`.pkg`) *must* be signed with EdDSA.
     * [Binary Delta updates](/documentation/delta-updates/) *must* be signed with EdDSA.
     * [Updates of preference panes and plugins](/documentation/bundles/) *must* be signed with EdDSA.
-    * Updates to regular application bundles that are signed with Apple's Developer ID program are strongly recommended to be signed with EdDSA for better security and fallback. Sparkle now deprecates not using EdDSA for these updates.
+    * Updates to regular application bundles that are signed with Apple's Developer ID program are strongly recommended to be signed with EdDSA for better security and fallback. Not using EdDSA signing for these updates is deprecated.
 
 Please ensure your signing keys are kept safe and cannot be stolen if your web server is compromised. One way to ensure this for example is not having your signing keys accessible from the machine that is hosting your product.
 
@@ -133,7 +133,7 @@ If you are code-signing your application via Apple's Developer ID program, Spark
 
 #### Rotating signing keys
 
-For regular application updates, if you both code-sign your application with Apple's Developer ID program and include a public EdDSA key for signing your update archive, Sparkle allows rotating keys by issuing a new update that changes either your Apple code signing certificate or your EdDSA keys.
+For regular application updates, if you both code-sign your application with Apple's Developer ID program and include a public EdDSA key for signing your update archive, Sparkle allows rotating keys by issuing a new update that changes either your Apple code signing certificate or your EdDSA keys (but not both). For applications that opt into enabling [SUVerifyUpdateBeforeExtraction](/documentation/customization/), the update archive must also be an Apple Developer ID code signed disk image.
 
 We recommend rotating keys only when necessary like if you need to change your Developer ID certificate, lose access to your EdDSA private key, or need to change (Ed)DSA keys due to [migrating away from DSA](eddsa-migration).
 
@@ -153,7 +153,7 @@ If you distribute your app on your website as a ZIP or a tar archive (due to [ap
 
 If your app is running from a read-only mount, you can encourage (if you want) your user to move the app into /Applications. Some frameworks, although not officially sanctioned here, exist for this purpose. Note Sparkle will not by default automatically disturb your user if an update cannot be performed.
 
-Sparkle supports updating from DMG, ZIP archives, tarballs, and [installer packages](/documentation/package-updates/), so you can generally reuse the same archive for distribution of your app on your website as well as Sparkle updates.
+Sparkle supports updating from DMG, ZIP archives, tarballs, Apple Archives (as of Sparkle 2.7 beta / macOS 10.15), and [installer packages](/documentation/package-updates/), so you can generally reuse the same archive for distribution of your app on your website as well as Sparkle updates.
 
 ### 5. Publish your appcast
 
@@ -164,7 +164,7 @@ Sparkle uses appcasts to get information about software updates. An appcast is a
 
 If you update regular app bundles and you have set up EdDSA signatures, you can use a tool to generate appcasts automatically:
 
-  1. Build your app and compress it (e.g. in a ZIP/tar.xz/DMG archive), and put the archive in a new folder. This folder will be used to store all your future updates.
+  1. Build your app and compress it (e.g. in a DMG/ZIP/tar.xz/.aar archive), and put the archive in a new folder. This folder will be used to store all your future updates.
   2. Run `generate_appcast` tool from Sparkle's distribution archive specifying the path to the folder with update archives. Allow it to access the Keychain if it asks for it (it's needed to generate signatures in the appcast).
 
         ./bin/generate_appcast /path/to/your/updates_folder/

documentation/publishing/index.md

@@ -9,23 +9,27 @@ So you're ready to release a new version of your app. How do you go about doing
 
 ### Archive your app
 
-Put a copy of your .app (with the same name as the version it's replacing) in a .zip, .tar.xz, or .dmg.
+Put a copy of your .app (with the same name as the version it's replacing) in a .dmg, .zip, .tar.\*, or .aar.
 
 Make sure symlinks are preserved when you create the archive. macOS frameworks use symlinks, and their code signature will be broken if your archival tool follows symlinks instead of archiving them.
 
-For creating zip archives, `ditto` can be used (behaves similar to Finder's Compress option):
+For creating dmg archives, APFS formatted images that use lzfse compression are recommended for decent decompression speed.
+
+For creating zip archives, use `ditto` (behaves similar to Finder's Compress option):
 
 ```sh
 ditto -c -k --sequesterRsrc --keepParent MyApp.app MyApp.zip
 ```
 
-For creating a LZMA compressed archive with optimal compression (but slower decompression), `tar` can be used for updates instead:
+For creating tar archives, stripping extended attributes is recommended for backwards compatibility from older systems. This example creates a LZMA compressed tar archive with high compression (but slower decompression).
 
 ```sh
 tar --no-xattrs -cJf MyApp.tar.xz MyApp.app
 ```
 
-Note this assumes your application does not use extended attributes and [places code and data into their proper places](https://developer.apple.com/documentation/bundleresources/placing_content_in_a_bundle) because creating a tar with extended attributes may cause extraction issues on older systems.
+Note `--no-xattrs` assumes your application and its code signature does not rely on extended attributes and [places code and data into their proper places](https://developer.apple.com/documentation/bundleresources/placing_content_in_a_bundle).
+
+For creating Apple Archives (`.aar`), check `man aa`. Sparkle 2.7 (beta) / macOS 10.15+ support this format. Enabling [SUVerifyUpdateBeforeExtraction](/documentation/customization/) is required for using this archive type.
 
 Please see [notes for Installer packages](/documentation/package-updates) if you are not updating a regular bundle.
 

documentation/upgrading/index.md

@@ -6,6 +6,12 @@ title: Upgrading from previous versions of Sparkle
 
 We strongly recommend upgrading Sparkle to the [latest production release](//github.com/{{ site.github_username }}/Sparkle/releases) because there have been [important security and reliability improvements](/documentation/security-and-reliability). Very old versions of Sparkle also suffer some incompatibilities with the latest macOS versions.
 
+## Upgrading to Sparkle 2.7 (beta)
+
+Sparkle 2.7 (beta) introduces a new format for delta updates, which preserves the creation date of the app bundle and creates slightly more efficient patches. If you don't use `generate_appcast`, please check the [compatibility notes for creating delta updates](/documentation/delta-updates/#compatibility).
+
+[Custom version comparators](/documentation/api-reference/Protocols/SPUUpdaterDelegate.html#/c:objc(pl)SPUUpdaterDelegate(im)versionComparatorForUpdater:) have been deprecated. Please use an increasing (numerical `x`, `x.y`, or `x.y.z`) `CFBundleVersion` / `sparkle:version` instead and disjoint them from more human presentable `CFBundleShortVersionString` / `sparkle:shortVersionString` if needed.
+
 ## Upgrading to Sparkle 2.6
 
 Sparkle 2.6 no longer sandboxes the Downloader XPC Service by default. If you enabled this XPC Service, please see the updated [sandboxing guide](/documentation/sandboxing) for more information.