[WIP] operating system incompatibility

docs/best-practices/linux-windows.md

@@ -0,0 +1,91 @@
+# Using _fastlane_ on Linux and Windows
+
+_fastlane_ was created to automate building iOS apps on macOS. Over time, support for building macOS and Android applications was added.
+
+Over the last few months members of the [_fastlane_ team](https://github.com/fastlane/fastlane#fastlane-team) have worked on improving the support for operating systems besides macOS with _fastlane_, namely Linux and Windows
+
+## Installation
+
+Follow the normal installation instructions:
+
+- [Getting started with _fastlane_ for iOS](https://docs.fastlane.tools/getting-started/ios/setup/)
+- [Getting started with _fastlane_ for Android](https://docs.fastlane.tools/getting-started/android/setup/)
+
+## Unsupported functionality
+
+_fastlane_ includes some functionality that does only work on macOS as it uses software that is not available on all other platforms as for example [Xcode](https://developer.apple.com/xcode/), [Keychain](https://support.apple.com/guide/keychain-access/what-is-keychain-access-kyca1083/mac), [`xcodebuild`](https://developer.apple.com/library/archive/technotes/tn2339/_index.html), [`security`](https://ss64.com/osx/security.html) or [`PTY`](http://man7.org/linux/man-pages/man7/pty.7.html). Where possible, we added alternatives inside the _fastlane_ codebase, but this was not possible everywhere. Whenever any of these softwares or tools are triggered in _fastlane_, a crash will inevitably follow on Windows and Linux.
+
+To avoid this we went through all actions and marked the ones using unsupported software as "incompatible" to those operating systems. When _fastlane_ executes such an action, it will check this list and throw an _exception_ with a message and a link to this page instead of crashing uncontrollably. This clearly communicates that some functionality is not available on a platform:
+
+```
+...
+[17:35:34]: Driving the lane 'test' 🚀
++---------------+------+
+|     Lane Context     |
++---------------+------+
+| PLATFORM_NAME |      |
+| LANE_NAME     | test |
++---------------+------+
+[16:39:53]: Action 'scan' is not compatible with operating system 'Windows'. For information how to handle this check out: TODO
+[16:39:53]: fastlane finished with errors
+
+[!] Action 'scan' is not compatible with operating system 'Windows'. For information how to handle this check out: TODO
+```
+
+The compatibility or incompatibility of actions is documented in the [list of available actions](https://docs.fastlane.tools/actions/).
+
+### Handling different operating systems in your `Fastfile`
+
+If you have lanes that should run on multiple operating systems with different compatibility for the actions used, you can wrap the calls of those actions in an `if` block to make sure it is skipped:
+
+```ruby
+lane :foo do
+  if Helper.is_mac?
+    scan
+  else
+    puts "Skipping tests as only possible on Mac"
+  end
+
+  if !Helper.is_windows?
+    build_app
+  end
+end
+```
+
+This way you can e.g. upload a build that is created on the fly on macOS, but use a file from the file system (that was created on a macOS machine before) on Linux or Windows.
+
+### Running unsupported functionality anyway
+
+You can set the environment variable `FASTLANE_IGNORE_OS_INCOMPAT` to override this behavior. The exception is then replaced with a non-blocking error that is output on the console. This is meant for those hackers out there working on making the tools work on other platforms anyway, and also as a way to override this behavior if we ever get an action wrong and some parts of it maybe work on those operating systems anyway.
+
+```
+...
+[17:36:19]: Driving the lane 'test' 🚀
+[17:36:19]: ------------------------------------------------
+[17:36:19]: Action 'scan' is not compatible with operating system 'Windows'. For information how to handle this check out: TODO
+[17:36:19]: Continuing anyway as `FASTLANE_IGNORE_OS_INCOMPAT` environment variable is set.
+[17:36:19]: ------------------------------------------------
+[17:36:19]: ------------------
+[17:36:19]: --- Step: scan ---
+[17:36:19]: ------------------
+...
+```
+
+### Documenting incompatibilities in custom or plugin action
+
+To support this incompatibility check in your custom or plugin actions, simply create an `is_incompatible?()` action that takes the `operating_system` as a string parameter. It should return `true` if the supplied operating system is not supported:
+
+```ruby
+def self.is_incompatible?(operating_system)
+  # you can do things like
+  #
+  #  operating_system != "macOS"
+  #
+  #  ["macOS", "Linux", "Windows"].include?(operating_system)
+  #
+
+  false
+end
+```
+
+New actions generated with `fastlane new_action` or `fastlane new_plugin` automatically include this method.

docs/index.md

@@ -81,6 +81,8 @@ _fastlane_ is officially supported to run on macOS.
 
 🐧 Linux and 🖥️ Windows are partially supported. Some underlying software like Xcode are only available on macOS, but many other tools, actions, and the `spaceship` module can work on other platforms.
 
+For more information, see [Using _fastlane_ on Linux and Windows](https://docs.fastlane.tools/best-practices/linux-windows/).
+
 ## _fastlane_ team
 
 <table>
@@ -168,12 +170,12 @@ _fastlane_ is officially supported to run on macOS.
 Special thanks to all [contributors](https://github.com/fastlane/fastlane/graphs/contributors) for extending and improving _fastlane_.
 
 ## Metrics
- 
-_fastlane_ tracks a few key metrics to understand how developers are using the tool and to help us know what areas need improvement. No personal/sensitive information is ever collected. Metrics that are collected include: 
- 
+
+_fastlane_ tracks a few key metrics to understand how developers are using the tool and to help us know what areas need improvement. No personal/sensitive information is ever collected. Metrics that are collected include:
+
 * The number of _fastlane_ runs
 * A salted hash of the app identifier or package name, which helps us anonymously identify unique usage of _fastlane_
- 
+
 You can easily opt-out of metrics collection by adding `opt_out_usage` at the top of your `Fastfile` or by setting the environment variable `FASTLANE_OPT_OUT_USAGE`. [Check out the metrics code on GitHub](https://github.com/fastlane/fastlane/tree/master/fastlane_core/lib/fastlane_core/analytics)
 
 ## License