Merge pull request #5670 from electron/custom-fork-docs

Create guide for how to create your own from-source Electron fork

docs/tutorial/application-distribution.md

@@ -125,3 +125,50 @@ packaging tools to do the work for you:
 
 * [electron-packager](https://github.com/maxogden/electron-packager)
 * [electron-builder](https://github.com/loopline-systems/electron-builder)
+
+### Creating a Custom Electron Fork
+
+Creating a custom fork of Electron is almost certainly not something you will
+need to do in order to build your app, even for "Production Level" applications.
+Using a tool such as `electron-packager` or `electron-builder` will allow you to
+"Rebrand" Electron without having to do these steps.
+
+You need to fork Electron when you have custom C++ code that you have patched
+directly into Electron, that either cannot be upstreamed, or has been rejected
+from the official version. As maintainers of Electron, we very much would like
+to make your scenario work, so please try as hard as you can to get your changes
+into the official version of Electron, it will be much much easier on you, and
+we appreciate your help.
+
+#### Creating a Custom Release with surf-build
+
+1. Install [Surf](https://github.com/surf-build/surf), via npm:
+  `npm install -g surf-build@latest`
+
+2. Create a new S3 bucket and create the following empty directory structure:
+
+```
+- atom-shell/
+  - symbols/
+  - dist/
+```
+
+3. Set the following Environment Variables:
+
+  * `ELECTRON_GITHUB_TOKEN` - a token that can create releases on GitHub
+  * `ELECTRON_S3_ACCESS_KEY`, `ELECTRON_S3_BUCKET`, `ELECTRON_S3_SECRET_KEY` -
+    the place where you'll upload node.js headers as well as symbols
+  * `ELECTRON_RELEASE` - Set to `true` and the upload part will run, leave unset
+    and `surf-build` will just do CI-type checks, appropriate to run for every
+    pull request.
+  * `CI` - Set to `true` or else it will fail
+  * `GITHUB_TOKEN` - set it to the same as `ELECTRON_GITHUB_TOKEN`
+  * `SURF_TEMP` - set to `C:\Temp` on Windows to prevent path too long issues
+  * `TARGET_ARCH` - set to `ia32` or `x64`  
+
+4. In `script/upload.py`, you _must_ set `ELECTRON_REPO` to your fork (`MYORG/electron`),
+  especially if you are a contributor to Electron proper.
+
+5. `surf-build -r https://github.com/MYORG/electron -s YOUR_COMMIT -n 'surf-PLATFORM-ARCH'`
+
+6. Wait a very, very long time for the build to complete.