feat(deployment): Building and Releasing using Channels

Close #1182

docs/api/electron-builder.md

@@ -10,13 +10,7 @@ Developer API only. See [Configuration](/configuration/configuration.md) for use
     * [`.BeforeBuildContext`](#BeforeBuildContext)
     * [`.BuildResult`](#BuildResult)
     * [`.CertificateFromStoreInfo`](#CertificateFromStoreInfo)
-    * [`.CommonLinuxOptions`](#CommonLinuxOptions)
-    * [`.CommonNsisOptions`](#CommonNsisOptions)
     * [`.FileCodeSigningInfo`](#FileCodeSigningInfo)
-    * [`.FileSet`](#FileSet)
-    * [`.ForgeOptions`](#ForgeOptions)
-    * [`.LinuxTargetSpecificOptions`](#LinuxTargetSpecificOptions) ⇐ <code>[CommonLinuxOptions](#CommonLinuxOptions)</code>
-    * [`.PlatformSpecificBuildOptions`](#PlatformSpecificBuildOptions) ⇐ <code>[TargetSpecificOptions](#TargetSpecificOptions)</code>
     * [`.SourceRepositoryInfo`](#SourceRepositoryInfo)
     * [.AppInfo](#AppInfo)
         * [`.computePackageUrl()`](#module_electron-builder.AppInfo+computePackageUrl) ⇒ <code>Promise&lt; \| String&gt;</code>
@@ -87,85 +81,13 @@ Developer API only. See [Configuration](/configuration/configuration.md) for use
 * **<code id="CertificateFromStoreInfo-store">store</code>** String
 * **<code id="CertificateFromStoreInfo-isLocalMachineStore">isLocalMachineStore</code>** Boolean
 
-<a name="CommonLinuxOptions"></a>
-## `CommonLinuxOptions`
-**Kind**: interface of [<code>electron-builder</code>](#module_electron-builder)<br/>
-**Properties**
-* <code id="CommonLinuxOptions-synopsis">synopsis</code> String - The [short description](https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Description).
-* <code id="CommonLinuxOptions-description">description</code> String - As [description](/configuration/configuration.md#Metadata-description) from application package.json, but allows you to specify different for Linux.
-* <code id="CommonLinuxOptions-category">category</code> String - The [application category](https://specifications.freedesktop.org/menu-spec/latest/apa.html#main-category-registry).
-* <code id="CommonLinuxOptions-desktop">desktop</code> any - The [Desktop file](https://developer.gnome.org/integration-guide/stable/desktop-files.html.en) entries (name to value).
-
-<a name="CommonNsisOptions"></a>
-## `CommonNsisOptions`
-**Kind**: interface of [<code>electron-builder</code>](#module_electron-builder)<br/>
-**Properties**
-* <code id="CommonNsisOptions-unicode">unicode</code> = `true` Boolean - Whether to create [Unicode installer](http://nsis.sourceforge.net/Docs/Chapter1.html#intro-unicode).
-* <code id="CommonNsisOptions-guid">guid</code> String - See [GUID vs Application Name](../configuration/nsis.md#guid-vs-application-name).
-* <code id="CommonNsisOptions-warningsAsErrors">warningsAsErrors</code> = `true` Boolean - If `warningsAsErrors` is `true` (default): NSIS will treat warnings as errors. If `warningsAsErrors` is `false`: NSIS will allow warnings.
-
 <a name="FileCodeSigningInfo"></a>
 ## `FileCodeSigningInfo`
 **Kind**: interface of [<code>electron-builder</code>](#module_electron-builder)<br/>
 **Properties**
 * **<code id="FileCodeSigningInfo-file">file</code>** String
 * <code id="FileCodeSigningInfo-password">password</code> String
 
-<a name="FileSet"></a>
-## `FileSet`
-**Kind**: interface of [<code>electron-builder</code>](#module_electron-builder)<br/>
-**Properties**
-* <code id="FileSet-from">from</code> String - The source path relative to the project directory.
-* <code id="FileSet-to">to</code> String - The destination path relative to the app's content directory for `extraFiles` and the app's resource directory for `extraResources`.
-* <code id="FileSet-filter">filter</code> Array&lt;String&gt; | String - The [glob patterns](/file-patterns.md).
-
-<a name="ForgeOptions"></a>
-## `ForgeOptions`
-**Kind**: interface of [<code>electron-builder</code>](#module_electron-builder)<br/>
-**Properties**
-* **<code id="ForgeOptions-dir">dir</code>** String
-
-<a name="LinuxTargetSpecificOptions"></a>
-## `LinuxTargetSpecificOptions` ⇐ <code>[CommonLinuxOptions](#CommonLinuxOptions)</code>
-**Kind**: interface of [<code>electron-builder</code>](#module_electron-builder)<br/>
-**Extends**: <code>[CommonLinuxOptions](#CommonLinuxOptions)</code>, <code>[TargetSpecificOptions](#TargetSpecificOptions)</code>  
-**Properties**
-* <code id="LinuxTargetSpecificOptions-depends">depends</code> Array&lt;String&gt; - Package dependencies.
-* <code id="LinuxTargetSpecificOptions-icon">icon</code> String
-* <code id="LinuxTargetSpecificOptions-packageCategory">packageCategory</code> String - The package category.
-* <code id="LinuxTargetSpecificOptions-vendor">vendor</code> String
-* <code id="LinuxTargetSpecificOptions-maintainer">maintainer</code> String
-* <code id="LinuxTargetSpecificOptions-afterInstall">afterInstall</code> String
-* <code id="LinuxTargetSpecificOptions-afterRemove">afterRemove</code> String
-* <code id="LinuxTargetSpecificOptions-synopsis">synopsis</code> String - The [short description](https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Description).
-* <code id="LinuxTargetSpecificOptions-description">description</code> String - As [description](/configuration/configuration.md#Metadata-description) from application package.json, but allows you to specify different for Linux.
-* <code id="LinuxTargetSpecificOptions-category">category</code> String - The [application category](https://specifications.freedesktop.org/menu-spec/latest/apa.html#main-category-registry).
-* <code id="LinuxTargetSpecificOptions-desktop">desktop</code> any - The [Desktop file](https://developer.gnome.org/integration-guide/stable/desktop-files.html.en) entries (name to value).
-* <code id="LinuxTargetSpecificOptions-artifactName">artifactName</code> String - The [artifact file name template](/configuration/configuration.md#artifact-file-name-template).
-* <code id="LinuxTargetSpecificOptions-publish">publish</code> String | [GithubOptions](/configuration/publish.md#githuboptions) | [S3Options](/configuration/publish.md#s3options) | [SpacesOptions](/configuration/publish.md#spacesoptions) | [GenericServerOptions](/configuration/publish.md#genericserveroptions) | [BintrayOptions](/configuration/publish.md#bintrayoptions) | Array
-
-<a name="PlatformSpecificBuildOptions"></a>
-## `PlatformSpecificBuildOptions` ⇐ <code>[TargetSpecificOptions](#TargetSpecificOptions)</code>
-**Kind**: interface of [<code>electron-builder</code>](#module_electron-builder)<br/>
-**Extends**: <code>[TargetSpecificOptions](#TargetSpecificOptions)</code>  
-**Properties**
-* <code id="PlatformSpecificBuildOptions-artifactName">artifactName</code> String - The [artifact file name template](/configuration/configuration.md#artifact-file-name-template). Defaults to `${productName}-${version}.${ext}` (some target can have other defaults, see corresponding options).
-* <code id="PlatformSpecificBuildOptions-files">files</code> Array&lt;String | [FileSet](#FileSet)&gt; | [FileSet](#FileSet) | String
-* <code id="PlatformSpecificBuildOptions-extraResources">extraResources</code> Array&lt;String | [FileSet](#FileSet)&gt; | [FileSet](#FileSet) | String
-* <code id="PlatformSpecificBuildOptions-extraFiles">extraFiles</code> Array&lt;String | [FileSet](#FileSet)&gt; | [FileSet](#FileSet) | String
-* <code id="PlatformSpecificBuildOptions-asar">asar</code> = `true` [AsarOptions](#AsarOptions) | Boolean - Whether to package the application's source code into an archive, using [Electron's archive format](http://electron.atom.io/docs/tutorial/application-packaging/).
-
-  Node modules, that must be unpacked, will be detected automatically, you don't need to explicitly set [asarUnpack](#configuration-asarUnpack) - please file an issue if this doesn't work.
-* <code id="PlatformSpecificBuildOptions-asarUnpack">asarUnpack</code> Array&lt;String&gt; | String - A [glob patterns](/file-patterns.md) relative to the [app directory](#MetadataDirectories-app), which specifies which files to unpack when creating the [asar](http://electron.atom.io/docs/tutorial/application-packaging/) archive.
-* <code id="PlatformSpecificBuildOptions-fileAssociations">fileAssociations</code> Array&lt;[FileAssociation](#FileAssociation)&gt; | [FileAssociation](#FileAssociation) - The file associations.
-* <code id="PlatformSpecificBuildOptions-protocols">protocols</code> Array&lt;[Protocol](#Protocol)&gt; | [Protocol](#Protocol) - The URL protocol schemes.
-* <code id="PlatformSpecificBuildOptions-forceCodeSigning">forceCodeSigning</code> Boolean
-* <code id="PlatformSpecificBuildOptions-publish">publish</code> String | [GithubOptions](/configuration/publish.md#githuboptions) | [S3Options](/configuration/publish.md#s3options) | [SpacesOptions](/configuration/publish.md#spacesoptions) | [GenericServerOptions](/configuration/publish.md#genericserveroptions) | [BintrayOptions](/configuration/publish.md#bintrayoptions) | Array
-* <code id="PlatformSpecificBuildOptions-releaseInfo">releaseInfo</code> [ReleaseInfo](#ReleaseInfo) - The release info. Intended for command line usage:
-
-  ``` -c.releaseInfo.releaseNotes="new features" ```
-* <code id="PlatformSpecificBuildOptions-target">target</code> Array&lt;String | [TargetConfiguration](#TargetConfiguration)&gt; | String | [TargetConfiguration](#TargetConfiguration)
-
 <a name="SourceRepositoryInfo"></a>
 ## `SourceRepositoryInfo`
 **Kind**: interface of [<code>electron-builder</code>](#module_electron-builder)<br/>

docs/configuration/configuration.md

@@ -92,8 +92,6 @@ Env file `electron-builder.env` in the current dir ([example](https://github.com
 ---
 
 * <code id="Configuration-buildVersion">buildVersion</code> String - The build version. Maps to the `CFBundleVersion` on macOS, and `FileVersion` metadata property on Windows. Defaults to the `version`. If `TRAVIS_BUILD_NUMBER` or `APPVEYOR_BUILD_NUMBER` or `CIRCLE_BUILD_NUM` or `BUILD_NUMBER` or `bamboo.buildNumber` env defined, it will be used as a build version (`version.build_number`).
-* <code id="Configuration-detectUpdateChannel">detectUpdateChannel</code> = `true` Boolean - Whether to infer update channel from application version pre-release components. e.g. if version `0.12.1-alpha.1`, channel will be set to `alpha`. Otherwise to `latest`.
-* <code id="Configuration-generateUpdatesFilesForAllChannels">generateUpdatesFilesForAllChannels</code> = `true` Boolean - Please see [Building and Releasing using Channels](https://github.com/electron-userland/electron-builder/issues/1182#issuecomment-324947139).
 * <code id="Configuration-electronCompile">electronCompile</code> Boolean - Whether to use [electron-compile](http://github.com/electron/electron-compile) to compile app. Defaults to `true` if `electron-compile` in the dependencies. And `false` if in the `devDependencies` or doesn't specified.
 * <code id="Configuration-electronDist">electronDist</code> String - The path to custom Electron build (e.g. `~/electron/out/R`).
 * <code id="Configuration-electronDownload">electronDownload</code><a name="ElectronDownloadOptions"></a> - The [electron-download](https://github.com/electron-userland/electron-download#usage) options.

docs/generated/PlatformSpecificBuildOptions.md

@@ -27,6 +27,8 @@
 
 * <code id="PlatformSpecificBuildOptions-forceCodeSigning">forceCodeSigning</code> Boolean
 * <code id="PlatformSpecificBuildOptions-publish">publish</code> The [publish](/configuration/publish.md) options.
+* <code id="PlatformSpecificBuildOptions-detectUpdateChannel">detectUpdateChannel</code> = `true` Boolean - Whether to infer update channel from application version pre-release components. e.g. if version `0.12.1-alpha.1`, channel will be set to `alpha`. Otherwise to `latest`.
+* <code id="PlatformSpecificBuildOptions-generateUpdatesFilesForAllChannels">generateUpdatesFilesForAllChannels</code> = `false` Boolean - Please see [Building and Releasing using Channels](https://github.com/electron-userland/electron-builder/issues/1182#issuecomment-324947139).
 * <code id="PlatformSpecificBuildOptions-releaseInfo">releaseInfo</code><a name="ReleaseInfo"></a> - The release info. Intended for command line usage:
 
   ``` -c.releaseInfo.releaseNotes="new features" ```

packages/electron-builder/src/configuration.ts

@@ -121,18 +121,6 @@ export interface Configuration extends PlatformSpecificBuildOptions {
    */
   readonly buildVersion?: string | null
 
-  /**
-   * Whether to infer update channel from application version pre-release components. e.g. if version `0.12.1-alpha.1`, channel will be set to `alpha`. Otherwise to `latest`.
-   * @default true
-   */
-  readonly detectUpdateChannel?: boolean
-
-  /**
-   * Please see [Building and Releasing using Channels](https://github.com/electron-userland/electron-builder/issues/1182#issuecomment-324947139).
-   * @default true
-   */
-  readonly generateUpdatesFilesForAllChannels?: boolean
-
   /**
    * Whether to use [electron-compile](http://github.com/electron/electron-compile) to compile app. Defaults to `true` if `electron-compile` in the dependencies. And `false` if in the `devDependencies` or doesn't specified.
    */

packages/electron-builder/src/options/PlatformSpecificBuildOptions.ts

@@ -68,6 +68,18 @@ export interface PlatformSpecificBuildOptions extends TargetSpecificOptions {
 
   publish?: Publish
 
+  /**
+   * Whether to infer update channel from application version pre-release components. e.g. if version `0.12.1-alpha.1`, channel will be set to `alpha`. Otherwise to `latest`.
+   * @default true
+   */
+  readonly detectUpdateChannel?: boolean
+
+  /**
+   * Please see [Building and Releasing using Channels](https://github.com/electron-userland/electron-builder/issues/1182#issuecomment-324947139).
+   * @default false
+   */
+  readonly generateUpdatesFilesForAllChannels?: boolean
+
   /**
    * The release info. Intended for command line usage:
    *

packages/electron-builder/src/publish/PublishManager.ts

@@ -341,12 +341,17 @@ function expandPublishConfig(options: any, packager: PlatformPackager<any>, arch
   }
 }
 
+function isDetectUpdateChannel(packager: PlatformPackager<any>) {
+  const value = packager.platformSpecificBuildOptions.detectUpdateChannel
+  return value == null ? packager.config.detectUpdateChannel !== false : value
+}
+
 async function getResolvedPublishConfig(packager: PlatformPackager<any>, options: PublishConfiguration, arch: Arch | null, errorIfCannot: boolean = true): Promise<PublishConfiguration | GithubOptions | BintrayOptions | null> {
   options = Object.assign(Object.create(null), options)
   expandPublishConfig(options, packager, arch)
 
   let channelFromAppVersion: string | null = null
-  if ((options as any).channel == null && packager.config.detectUpdateChannel !== false) {
+  if ((options as any).channel == null && isDetectUpdateChannel(packager)) {
     channelFromAppVersion = packager.appInfo.channel
   }
 

packages/electron-builder/src/publish/updateUnfoBuilder.ts

@@ -24,6 +24,35 @@ async function getReleaseInfo(packager: PlatformPackager<any>) {
   return releaseInfo
 }
 
+function isGenerateUpdatesFilesForAllChannels(packager: PlatformPackager<any>) {
+  const value = packager.platformSpecificBuildOptions.generateUpdatesFilesForAllChannels
+  return value == null ? packager.config.generateUpdatesFilesForAllChannels : value
+}
+
+/**
+ if this is an "alpha" version, we need to generate only the "alpha" .yml file
+ if this is a "beta" version, we need to generate both the "alpha" and "beta" .yml file
+ if this is a "stable" version, we need to generate all the "alpha", "beta" and "stable" .yml file
+ */
+function computeChannelNames(packager: PlatformPackager<any>, publishConfig: PublishConfiguration) {
+  const currentChannel: string = (publishConfig as GenericServerOptions).channel || "latest"
+  // for GitHub should be pre-release way be used
+  if (currentChannel === "alpha" || publishConfig.provider === "github" || !isGenerateUpdatesFilesForAllChannels(packager)) {
+    return [currentChannel]
+  }
+
+  switch (currentChannel) {
+    case "beta":
+      return [currentChannel, "alpha"]
+
+    case "latest":
+      return [currentChannel, "alpha", "beta"]
+
+    default:
+      return [currentChannel]
+  }
+}
+
 /** @internal */
 export async function writeUpdateInfo(event: ArtifactCreated, _publishConfigs: Array<PublishConfiguration>): Promise<Array<ArtifactCreated>> {
   const packager = event.packager
@@ -40,7 +69,6 @@ export async function writeUpdateInfo(event: ArtifactCreated, _publishConfigs: A
   const sharedInfo = await createUpdateInfo(version, event, await getReleaseInfo(packager))
   const events: Array<ArtifactCreated> = []
   for (let publishConfig of publishConfigs) {
-    let info = sharedInfo
     if (publishConfig.provider === "bintray") {
       continue
     }
@@ -56,24 +84,15 @@ export async function writeUpdateInfo(event: ArtifactCreated, _publishConfigs: A
     }
 
     // spaces is a new publish provider, no need to keep backward compatibility
-    const isElectronUpdater1xCompatibility = publishConfig.provider !== "spaces"
-
-    const channel = (publishConfig as GenericServerOptions).channel || "latest"
-    if (isMac && isElectronUpdater1xCompatibility) {
-      await writeOldMacInfo(publishConfig, outDir, dir, channel, createdFiles, version, packager)
-    }
-
-    const updateInfoFile = path.join(dir, `${channel}${isMac ? "-mac" : ""}.yml`)
-    if (createdFiles.has(updateInfoFile)) {
-      continue
-    }
-
-    createdFiles.add(updateInfoFile)
+    let isElectronUpdater1xCompatibility = publishConfig.provider !== "spaces"
 
+    let info = sharedInfo
     // noinspection JSDeprecatedSymbols
-    if (isElectronUpdater1xCompatibility && packager.platform === Platform.WINDOWS && info.sha2 == null) {
-      // backward compatibility
-      (info as any).sha2 = await sha2.value
+    if (isElectronUpdater1xCompatibility && packager.platform === Platform.WINDOWS) {
+      info = {
+        ...info,
+        sha2: await sha2.value,
+      }
     }
 
     if (event.safeArtifactName != null && publishConfig.provider === "github") {
@@ -82,18 +101,34 @@ export async function writeUpdateInfo(event: ArtifactCreated, _publishConfigs: A
         githubArtifactName: event.safeArtifactName,
       }
     }
-    const fileContent = Buffer.from(safeDump(info))
-    await outputFile(updateInfoFile, fileContent)
 
-    // artifact should be uploaded only to designated publish provider
-    events.push({
-      file: updateInfoFile,
-      fileContent,
-      arch: null,
-      packager,
-      target: null,
-      publishConfig,
-    })
+    for (const channel of computeChannelNames(packager, publishConfig)) {
+      if (isMac && isElectronUpdater1xCompatibility) {
+        // write only for first channel (generateUpdatesFilesForAllChannels is a new functionality, no need to generate old mac update info file)
+        isElectronUpdater1xCompatibility = false
+        await writeOldMacInfo(publishConfig, outDir, dir, channel, createdFiles, version, packager)
+      }
+
+      const updateInfoFile = path.join(dir, `${channel}${isMac ? "-mac" : ""}.yml`)
+      if (createdFiles.has(updateInfoFile)) {
+        continue
+      }
+
+      createdFiles.add(updateInfoFile)
+
+      const fileContent = Buffer.from(safeDump(info))
+      await outputFile(updateInfoFile, fileContent)
+
+      // artifact should be uploaded only to designated publish provider
+      events.push({
+        file: updateInfoFile,
+        fileContent,
+        arch: null,
+        packager,
+        target: null,
+        publishConfig,
+      })
+    }
   }
   return events
 }

scripts/jsdoc2md.js

@@ -280,9 +280,12 @@ function sortOptions(pages) {
 
   const excluded = new Set(["CommonLinuxOptions", "CommonNsisOptions", "LinuxTargetSpecificOptions", "PlatformSpecificBuildOptions", "ForgeOptions", "FileSet"])
   electronBuilderApiPage.data = electronBuilderApiPage.data.filter(member => {
-    if (member.kind === "module" || excluded.has(member.name)) {
+    if (member.kind === "module") {
       return true
     }
+    if (excluded.has(member.name)) {
+      return false
+    }
     return !(isInlinedMember(member) || member.name.endsWith("Options") || member.name.endsWith("Configuration") || member.name === "Configuration" || member.name.startsWith("Metadata") || member.name.startsWith("Dmg"))
   })