Doc - Release using channels #2595

popod · 2018-02-16T21:39:22Z

todo:

improve documentation
review and fix english typos

develar · 2018-02-19T07:28:11Z

docs/tutorials/release-using-channels.md

@@ -0,0 +1,63 @@
+> !!! This documentation is in "beta" and needed to be tested !!!
+
+# Release using channels / Auto-updates with channels


Please in the future use form "Header Must Use Capital Case".

Thanks for the comment, I've change this.

develar · 2018-02-19T07:30:08Z

docs/tutorials/release-using-channels.md

+### Your application
+All you need to do here is to define which channel the user will receive.
+
+`autoUpdater.setFeedURL({url: 'https://www.yoursite.com', channel: 'beta'});`


Now user can set channel, setFeedURL not required, right?

I'm confused. Where do we set channel ?

Oh this:

electron-builder/packages/electron-updater/src/AppUpdater.ts

Line 73 in ba4809a

set channel(value: string | null) {

. Needs to be documented

@kwent and @develar Thanks for feedback. I've remove the "old" setFeedURL and replace it with autoUpdater.channel(). I will add the doc for channel() too.

kwent · 2018-02-22T06:55:49Z

One scary section to me was:

Do not call setFeedURL. electron-builder automatically creates app-update.yml file for you on build in the resources (this file is internal, you don't need to be aware of it).

Might want to modify this as well :)

kwent · 2018-02-28T23:40:55Z

docs/tutorials/release-using-channels.md


-`autoUpdater.channel('beta')`
+`autoUpdater.channel('beta')` (see [the documentation here](../auto-update.md#module_electron-updater.AppUpdater+channel))


I have been doing autoUpdater.channel = 'beta'. Is this valid as well ?

@kwent my bad.. channel('beta') is false. I will correct this.

popod · 2018-03-07T08:37:21Z

@develar and @kwent what do you think about this current "small tutorial" ? Have I miss something ?

rahilsondhi · 2018-03-07T08:58:27Z

docs/tutorials/release-using-channels.md

+
+Users which receive "beta" version will get "stable" versions too. Otherwise, users who don't want "beta" will only get "stable" releases.
+
+They are tree channels level ordered by stability:


typo. i think you meant to say "There are three channels, ordered by stability"

Thanks ! Yes this is exactly what I'm trying to say ;)

kwent · 2018-03-07T11:05:41Z

LGTM.

One thing i saw is if i set channel to stable the library was looking for stable-mac.yml. (I imagine same thing for windows and linux) but the packager is creating latest-mac.yml. Setting the channel to latest instead stable fixed it in my case (curiously you can set the channel to any string value as well...). Not sure if the autoupdater or the packager is wrong but something is not in phase.

Might not be the best place and might be worst opening an issue instead tho. cc @develar

Update: Found a previous comment from you @popod. So is it stable or latest ?. Is it depending of generateUpdatesFilesForAllChannels set or not ? We might wanna clear this out in the doc as well.

popod · 2018-03-07T18:55:21Z

@kwent thanks: this is an error! The channels to use are latest, beta and alpha, not stable. I think the easy way is that I use latest in place of stable in this doc. But stable seems to be more intuitive..

@develar do you see an other possibility ? Like as example set the channel to latest both when the user set it to stable and latest ?

(curiously you can set the channel to any string value as well...). Not sure if the autoupdater or the packager is wrong but something is not in phase.

And do you think that this is useful to limit the channel to latest, beta and alpha ?

kwent · 2018-03-07T19:18:05Z

Maybe we can alias stable to latest ? cc @develar

develar · 2018-03-07T19:57:08Z

And do you think that this is useful to limit the channel to latest, beta and alpha ?

No, user should be able to use whatever he want. But! Where do you set? updater.channel or electron-builder publish config channel?

develar · 2018-03-07T20:00:39Z

Obviously, that you cannot set updater.channel to stable if you use generateUpdatesFilesForAllChannels.

stable in our case it is latest. But tutorial has a lot of usages of word stable :) And actually, to set "stable" channel (as tutorial suggests), you need to set it to null or latest.

popod · 2018-03-07T20:10:28Z

@develar as I wrote in my latest comment, do you think that it is possible to do this:

When doing autoUpdater.channel = 'stable', in the setter function, change stable by latest ? As is, the tutorial will be correct. I think that the word "stable" is more logic than "latest" for a "user point of view" and according to the tutorial description.

And do you think that this is useful to limit the channel to latest, beta and alpha ?

No, user should be able to use whatever he want. But! Where do you set? updater.channel or electron-builder publish config channel?

With autoUpdater.channel = 'something'.

develar · 2018-03-07T20:10:36Z

Yeach... you are right. latest is not clear. Because actually, beta will point to stable release if for now stable release is the latest.

all application releases use the "stable" channel.

Well... no channel means that channels are not used and default name of update file is latest :)

Need to think about it. We cannot map stable to latest in the electron-updater, because electron-updater is not aware of generateUpdatesFilesForAllChannels. And electron-builder (if generateUpdatesFilesForAllChannels is set to default false) will generate stable update file instead of latest. I do not want to add this magic transformation.

Possible solution — if generateUpdatesFilesForAllChannels is set, stable will be generated instead of latest (and logic getDefaultChannelName of electron-updater will be not used because we will set channel by default explicitly to stable).

popod · 2018-03-07T20:34:01Z

Thanks for your reply @develar ! I understand and agree with the fact that we should no do "magic transformation" :)

I think that the auto-updater should be "compatible" if we use generateUpdatesFilesForAllChannels or not. So we need to keep the latest label. I think the easy way to solve this problem is that I update the tutorial with latest in place of stable.

I will do it tomorrow. If you have an other solution, let me know ;)

jake · 2018-03-07T20:43:16Z

Been loosely following this thread, and have actually got this multi-channel support working in my app. So, thanks for these WIP docs!

Isn't the feature already complete? Are we discussing improving how it works, or just documenting the way it currently works?

At the risk of getting off topic... I was definitely annoyed and disappointed that I had to use these magic variable names ("alpha" -> "beta" -> "latest"). For my workflow, I want "canary" -> "preview" -> "release".

I think hardcoding these release channel names is a very weird idea. Not only does it limit functionality, it's less clear how they relate. If you let the user define the flow of channels themselves, they can customize whatever (and however many) make sense for their application, and it also will likely make more sense overall since they set up the relationships themselves.

There should be a new concept introduced in this release channels feature, one of channel order. I think in the build settings, defining an ordered array would be great.

Maybe, if you wanted to keep a sane default around, you could make channels: true expand to:

channels:
  - alpha
  - beta
  - latest

Or, if you want something else as I'd like to you could define your own array:

channels:
  - canary
  - preview
  - release

If generateUpdatesFilesForAllChannels is set, the same logic that exists today is followed, where anything before the currently-being-built-to-channel in that array gets pushed the release as well. (e.g., if I was building "preview" it would also push to "canary").

Also, FWIW, generateUpdatesFilesForAllChannels is also a very confusingly named parameter. It doesn't generate updates for all channels. It controls whether or not to publish the update to any channel "before" the currently built to channel.

popod · 2018-03-07T21:08:01Z

@jake Thanks for your feedback !

Isn't the feature already complete? Are we discussing improving how it works, or just documenting the way it currently works?

Here, I think we should only "documenting the way it currently works". But we think about improving it too :)

Auto update with channel is available since a few month and no documentation existe about it until now.. As we discuss here: #1182 (comment), I already have suggest to let the user define it's own "channel name". But we kept things simple for the first working implementation.

I think that we should keep the "stable, beta, alpha" channels by default to provide an "easy to use" functionality, but allow advanced users to change this..

I don't know what think @develar about that, but I think we could open a new issue for let the users chose their "channels names" and the related order. I really think this is a pretty feature !

develar · 2018-03-07T21:20:22Z

Isn't the feature already complete?

Complete.

generateUpdatesFilesForAllChannels is also a very confusingly named parameter. It doesn't generate updates for all channels

Well, this option does exactly what name means — generates update info files for all channels :) As update info files is generated and uploaded, your users get updates.

@jake Do you realise and understand, that canary update info file will contain info about ** release** channel update when do you release a new version of app? e.g. after canary 20.3.0 you release 20.40.30 and so, all users of canary or preview channels must get updates from release channel (because at this moment no new canary or preview versions available).

For my workflow, I want "canary" -> "preview" -> "release".

@jake Do you use semver or not? I mean — canary Please provide example of canary version number.

develar · 2018-03-07T21:24:03Z

I think hardcoding these release channel names is a very weird idea. Not only does it limit functionality, it's less clear how they relate.

BTW, right now nothing stops you :) But it is your responsibility to copy/create/upload such update info files in this case right now. And thanks a lot to @popod, it is not good — electron-builder should help you to avoid manual uploading/copying.

jake · 2018-03-07T22:34:22Z

Sorry, I don't quite follow what you're asking. I also just wanted to reiterate I'm just trying to be helpful by providing some real world feedback :)

I don't use semver, as I think it's very non-human-friendly. I try to build software for humans, not robots. I understand its value in internal library world, but Electron is for end users. I'm not sure how relevant it is to this discussion, but here's our versioning strategy. Ideally the names would be what I described earlier. FWIW, Framer.js also uses a similar whole-version-number strategy.

my non-standard versioning strategy

Per the release channel docs (issue, pull), there are three release channels: Alpha, Beta, Stable.

Build artifacts have their version number (and thus their release channel) in the filename.

Once you download a release from a channel, you are subscribed to that channel. You can easily switch by downloading a release from a different channel.

Conceptually, we are working on 3.0.0 within the Alpha and Beta channels, and finally releasing it through the Stable channel. Once 3.0.0 is released on Stable we start work on 4.0.0 within the Alpha channel and repeat the workflow.

Alpha

Rolling time-based snapshots. Version is next potential for "Stable" channel. Internal only, bleeding edge. Commonly broken. Possibly CI-driven every commit.

3.0.0-alpha.20180218.093433
3.0.0-alpha.20180218.094454
3.0.0-alpha.20180218.112235

Note: Subscribers of Alpha also receives updates published to Beta and Stable.

Beta

Latest snapshot promoted to Beta channel for consideration. Limited pool of external testers. Supposed to work and be ready for public consumption.

3.0.0-beta

In the event a beta release has an issue, we issue hotfixes to the Beta channel.

3.0.0-beta.1
3.0.0-beta.2
3.0.0-beta.3

Note: we'd also be issuing additional releases on the Snapshot channel, e.g. 3.0.0-snapshot.TIMESTAMP, and once we solved the issue issuing new Beta channel releases.

Note: Subscribers of Beta also receives updates published to Stable.

Consider: TIMESTAMP on hotfix releases?

3.0.0-beta.20180218.112424
3.0.0-beta.20180218.125310
3.0.0-beta.20180219.152239

Stable

The publicly consumed versions. Guaranteed to work, as they passed through Snapshot and Beta channels. Only ever whole major versions with zeroed minor and patch versions.

1.0.0
2.0.0
3.0.0

Note: Subscribers of Stable only receive updates to Stable.

In your example, is it not still pushing to both the currently selected channel and any channels it supersedes?

If I'm building latest it pushes to latest, beta, and alpha
If I'm building beta, it pushes to beta and alpha
If I'm building alpha, it pushes to alpha

Isn't this always the case? Release channels cascade down. You never push a channel release "upstream"-- you wouldn't build an alpha release and push it to latest. However, you'd want people subscribed to a "downstream" channel to get anything upstream.

Well, this option does exactly what name means — generates update info files for all channels :) As update info files is generated and uploaded, your users get updates.

How so? I have this option enabled, and when I publish an "alpha" build my "latest" release file is not regenerated, or even re-uploaded as far as I can tell. Doesn't this option control the feature that pushes releases to downstream channels in addition to the selected channel?

right now nothing stops you

Are you proposing I fork electron-builder and change those hardcoded values?

develar · 2018-03-07T22:49:33Z

Are you proposing I fork electron-builder and change those hardcoded values?

These values are not harcoded — you can use any channel name as you want (but in this case electron-builder cannot help you to upload/regenerate corresponding update info files).

when I publish an "alpha" build my "latest" release file is not regenerated, or even re-uploaded as far as I can tell.

Yes. Because latest it is stable, and as you build alpha, only alpha is regenerated and uploaded.

Ok... so, as far I see from your example versions, you use pre-release version tags alpha and beta. But... you name (want to think in these terms, want to name it so) channels as canary and preview, right?

jake · 2018-03-07T23:09:18Z

These values are not harcoded — you can use any channel name as you want (but in this case electron-builder cannot help you to upload/regenerate corresponding update info files).

Oh, I see. I guess I'm somewhat conflating arbitrary release channels with the "sorted" hierarchical release channels as I've been describing (e.g. canary -> preview -> release).

The alpha -> beta -> latest release hierarchy is hardcoded though, right?

you use pre-release version tags alpha and beta. But... you name (want to think in these terms, want to name it so) channels as canary and preview, right?

Pretty much! I'm fighting against npm's annoyingly-hardcoded semver requirements. If I was just setting up a system without any limitations, I'd just use e.g. version v3-canary for the "canary" channel, v3-preview for "preview", and v3 for "release".

Anyway, if I can be of any help testing the future fully-customizable release channel hierarchy I'm game!

develar · 2018-03-07T23:20:53Z

Ok. So, @jake just want ability to setup own mappings. Default for now latest, beta, alpha. Here latest is not clear and probably we should rename it to stable.

I propose — if option generateUpdatesFilesForAllChannels is set to true, cascade stable-beta-alpha is used. Latest is not generated at all.

If set to array of string, each item it is a pre-release component except the first element — first It is name of a stable channel.

And so, updater.channel will forbid empty/null channel name to ensure that developer aware of default channel name).

jake · 2018-03-07T23:32:52Z

cascade stable-beta-alpha is used. Latest is not generated at all.

I'd challenge this idea. I think it might make most sense to have "latest" always mean "ready for production".

Would also make it easier to adopt named release channels later after already shipping your app. Otherwise, you need to account for apps in the wild that are subscribed to latest-mac.yml but you've begun to publish to stable-mac.yml.

I think if the definition of "latest" is just well defined, it can be clear enough. It might be more confusing introducing a new word, "stable"?

If set to array of string, each item it is a pre-release component except the first element — first It is name of a stable channel.

Smart- so cascade the array of channels down, from most stable to lease. Then it's easy to do channel[0] to find the most-stable, and can just slice the array at the current to get the additional downstream channels to write to. 👍

jake · 2018-03-07T23:43:42Z

Oh, just to clarify:

Have "latest" always mean "ready for production" unless you've defined your own release channel list. In which case, the first entry in your list represents "ready for production", and it's whatever name you've chosen for it.

develar · 2018-03-07T23:52:34Z

Then it's easy to do channel[0] to find the most-stable

Hmm... currently, we detect it using prerelease component of current app version. If no pre release component — only Most-stable channel file will be generated.

kwent · 2018-03-14T23:35:02Z

@popod @develar I think we need to fix the stable / latest ambiguous and this should be good to merge.

popod · 2018-03-22T12:39:12Z

@develar @kwent I've change the documentation by using "latest" in place of "stable". I think this is clear enough to deploy.

kwent · 2018-03-22T19:09:05Z

LGTM

develar · 2018-03-25T19:04:29Z

@popod Thanks a lot. The only reason why this awesome addition is not yet merged — I want to do some changes to address @jake suggestions.

JsseL · 2018-08-20T12:33:24Z

For those looking for a link to the docs.

First basic draft

3528b2d

popod mentioned this pull request Feb 16, 2018

Documentation - auto-update with channels #2593

Closed

popod added 2 commits February 16, 2018 22:47

Update summary with new tutorial link

06ec156

Doc improvments

a1944e5

develar reviewed Feb 19, 2018

View reviewed changes

Improve documentation based on feedbacks

43435e1

popod force-pushed the doc-release-using-channels branch from 578a60b to 667b982 Compare February 28, 2018 22:22

Add documentation for autoUpdater.channel()

dedc0e9

popod force-pushed the doc-release-using-channels branch from 667b982 to f31a826 Compare February 28, 2018 22:27

kwent reviewed Feb 28, 2018

View reviewed changes

Improve the documentation

130311e

popod force-pushed the doc-release-using-channels branch from 8b365c1 to 130311e Compare March 1, 2018 01:05

rahilsondhi reviewed Mar 7, 2018

View reviewed changes

Fix some typos

83e7d48

popod force-pushed the doc-release-using-channels branch from 9880d01 to 83e7d48 Compare March 7, 2018 09:28

Improve the "how to use it" section

a70e1ca

Title Should be Uppercased

e2d0339

Replace "stable" with "latest"

ea268be

develar merged commit 5b86d97 into electron-userland:master Mar 28, 2018

		@@ -0,0 +1,63 @@
		> !!! This documentation is in "beta" and needed to be tested !!!

		# Release using channels / Auto-updates with channels


		`autoUpdater.channel('beta')`
		`autoUpdater.channel('beta')` (see [the documentation here](../auto-update.md#module_electron-updater.AppUpdater+channel))


		Users which receive "beta" version will get "stable" versions too. Otherwise, users who don't want "beta" will only get "stable" releases.

		They are tree channels level ordered by stability:

Doc - Release using channels #2595

Doc - Release using channels #2595

Conversation

popod commented Feb 16, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kwent commented Feb 22, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

popod commented Mar 7, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kwent commented Mar 7, 2018 • edited Loading

popod commented Mar 7, 2018

kwent commented Mar 7, 2018 via email • edited Loading

develar commented Mar 7, 2018

develar commented Mar 7, 2018

popod commented Mar 7, 2018 • edited Loading

develar commented Mar 7, 2018

popod commented Mar 7, 2018

jake commented Mar 7, 2018

popod commented Mar 7, 2018

develar commented Mar 7, 2018 • edited Loading

develar commented Mar 7, 2018 • edited Loading

jake commented Mar 7, 2018 • edited Loading

Alpha

Beta

Stable

develar commented Mar 7, 2018 • edited Loading

jake commented Mar 7, 2018 • edited Loading

develar commented Mar 7, 2018

jake commented Mar 7, 2018

jake commented Mar 7, 2018

develar commented Mar 7, 2018

kwent commented Mar 14, 2018

popod commented Mar 22, 2018

kwent commented Mar 22, 2018

develar commented Mar 25, 2018

JsseL commented Aug 20, 2018

popod commented Feb 16, 2018 •

edited

Loading

kwent commented Mar 7, 2018 •

edited

Loading

kwent commented Mar 7, 2018 via email •

edited

Loading

popod commented Mar 7, 2018 •

edited

Loading

develar commented Mar 7, 2018 •

edited

Loading

develar commented Mar 7, 2018 •

edited

Loading

jake commented Mar 7, 2018 •

edited

Loading

develar commented Mar 7, 2018 •

edited

Loading

jake commented Mar 7, 2018 •

edited

Loading