Repository: electron
Issue: Improve autoUpdater documentation
Labels: documentation :notebook:,stale-exempt

Note: these issues were previously reported by @fabiospampinato in a separate issue. They have been grouped and some context/comments have been added to help.

The `autoUpdater` module is an important one that unfortunately is not documented enough.
This meta-issue lists different areas of improvements and links (when created) to the right
specific tasks in the right repos to track progress.

* [ ] Document the results returned by the update server for each platform (mac and Windows is different).
  > on mac it expects a JSON response if their is an update or a 204 response when their is no update. The windows auto updater requests a RELEASES plain text file and then parses that for assets to download and update to.
* [ ] Document what the server should return when there is no update available.
* [ ] Document what are the right arguments to be passed to the callback for "update-available".
  > like they say the release notes and the release date are always available, but even update.electronjs.org doesn't return all of that kind of information so that can't possibly be available under all circumstances.
* [ ] Clearly specify the right file formats for each platform. I.e.: Is mac zip only or can it be a DMG? What type of exe for Windows?
  > According to [this line](https://github.com/electron/update.electronjs.org/blob/5d6fc08374e14fba84e94dc1c70e1e19cbcbcf53/index.js#L264) the server should return a zip file for mac, does it just not work if a DMG is returned? What if I'm building the zip or dmg with electron-builder vs electron-forge, any differences there?

  > According to [these lines](https://github.com/electron/update.electronjs.org/blob/5d6fc08374e14fba84e94dc1c70e1e19cbcbcf53/index.js#L272-L274) it seems like the update for Windows can have whatever extension, which doesn't sound right to me, what's the expected format here?

  >According to [this line](https://github.com/electron/update.electronjs.org/blob/5d6fc08374e14fba84e94dc1c70e1e19cbcbcf53/index.js#L280) an exe for Windows should work, but what kind of exe are we taking about, would an NSIS build work? What about portable builds?
* [ ] Make sure the documentation between the [How to](https://www.electronjs.org/docs/latest/how-to/updates/) and the [API](https://www.electronjs.org/docs/latest/api/auto-updater/) stays in sync (e.g.: which platforms should be code-signed?)
* [ ] Document edge cases like the following:
  > if I'm running an x64 build for mac under rosetta, is it ok to have the server return me an arm64 update?
* [ ] Document what will happen if you try to update the application the first time it runs instead of linking to [an issue](https://github.com/electron/electron/issues/7155)
* [ ] Document possible issues with electron-builder
  > Honestly speaking, electron-builder is not supported by the Electron maintainers, there is nothing we can do to support that package and electron-builder has actively moved off of tooling that we provide and support. Things like electron-osx-sign, electron-packager and electron-forge are all effectively guaranteed to work with the Latest Electron things like structure changes and new architectures / features, we can't make any guarantees about electron-builder.
  > If you want to use electron provided and supported tooling, electron-builder isn't the right path for you.
* [ ] Mention ways to test this functionality locally
  > Pro-Tip, anywhere in Squirrel.Windows that you can put a HTTP URL, you can also put just a regular path to a folder. This makes testing updates much much easier, because you can just set your dist folder as the update URL
* [ ] Figure out what is the upgrade path for portable applications. Seems like it is not supported but some have done it
  > You can't call checkForUpdates unless you're an installed app
  
  > The canonical way to detect if you are a Squirrel-installed app if you're not into that is `fs.existsSync(path.resolve(path.dirname(process.execPath), '..', 'update.exe'));`

When talking with @MarshallOfSound he mentioned that most of this information is available in other repos (notably the squirrel ones, like this [macOS](https://github.com/Squirrel/Squirrel.Mac#server-support)). We should find out what is available and what not, and then decide if we should copy that information or at least point to the right place.