Document IPv6 workarounds. Fixes #4748.

doc/articles/troubleshooting.md

@@ -258,9 +258,53 @@ If you have been pointed to this page, you want to check a few things:
   with your ISP or server host, the problem is not at the Packagist level but in the
   routing rules between you and Packagist (i.e. the internet at large). The best way to get
   these fixed is raise awareness to the network engineers that have the power to fix it.
+  Take a look at the next section for IPv6 workarounds.
 
-  To disable IPv6 on Linux, try using this command which appends a
-  rule preferring IPv4 over IPv6 to your config:
-
-  `sudo sh -c "echo 'precedence ::ffff:0:0/96 100' >> /etc/gai.conf"`
 - If none of the above helped, please report the error.
+ 
+## Operation timed out (IPv6 issues)
+
+You may run into errors if IPv6 is not configured correctly. A common error is:
+
+```
+The "https://getcomposer.org/version" file could not be downloaded: failed to open stream: Operation timed out
+```
+
+We recommend you fix your IPv6 setup. If that is not possible, you can try the following workarounds:
+
+
+**Workaround Linux:**
+
+On linux, it seems that running this command helps to make ipv4 traffic have a higher prio than ipv6, which is a better alternative than disabling ipv6 entirely:
+
+```Bash
+sudo sh -c "echo 'precedence ::ffff:0:0/96 100' >> /etc/gai.conf"
+```
+
+**Workaround Windows:**
+
+On windows the only way is to disable ipv6 entirely I am afraid (either in windows or in your home router).
+
+**Workaround Mac OS X:**
+
+Get name of your network device:
+
+```
+networksetup -listallnetworkservices
+```
+
+Disable IPv6 on that device (in this case "Wi-Fi")
+
+```
+networksetup -setv6off Wi-Fi
+```
+
+Run composer ...
+
+You can enable IPv6 again with:
+
+```
+networksetup -setv6automatic Wi-Fi
+```
+
+That said, if this fixes your problem, please talk to your ISP about it to try and resolve the routing errors. That's the best way to get things resolved for everyone.