Merge pull request scratchfoundation#4717 from gunchleoc/add-troubleshooting-documentation

Add troubleshooting documentation

Author: paulkaplan

README.md

@@ -130,6 +130,66 @@ If you want to watch the browser as it runs the test, rather than running headle
 USE_HEADLESS=no $(npm bin)/jest --runInBand test/integration/backpack.test.js
 ```
 
+## Troubleshooting
+
+### Ignoring optional dependencies
+
+When running `npm install`, you can get warnings about optionsl dependencies:
+
+```
+npm WARN optional Skipping failed optional dependency /chokidar/fsevents:
+npm WARN notsup Not compatible with your operating system or architecture: [email protected]
+```
+
+You can suppress them by adding the `no-optional` switch:
+
+```
+npm install --no-optional
+```
+
+Further reading: [Stack Overflow](https://stackoverflow.com/questions/36725181/not-compatible-with-your-operating-system-or-architecture-fsevents1-0-11)
+
+### Resolving dependencies
+
+When installing for the first time, you can get warnings which need to be resolved:
+
+```
+npm WARN [email protected] requires a peer of babel-eslint@^8.0.1 but none was installed.
+npm WARN [email protected] requires a peer of eslint@^4.0 but none was installed.
+npm WARN [email protected] requires a peer of react-intl-redux@^0.7 but none was installed.
+npm WARN [email protected] requires a peer of react-responsive@^4 but none was installed.
+```
+
+You can check which versions are available:
+
+```
+npm view react-intl-redux@0.* version
+```
+
+You will neet do install the required version:
+
+```
+npm install  --no-optional --save-dev react-intl-redux@^0.7
+```
+
+The dependency itself might have more missing dependencies, which will show up like this:
+
+```
+user@machine:~/sources/scratch/scratch-gui (491-translatable-library-objects)$ npm install  --no-optional --save-dev react-intl-redux@^0.7
+[email protected] /media/cuideigin/Linux/sources/scratch/scratch-gui
+├── [email protected]
+└── UNMET PEER DEPENDENCY [email protected]
+```
+
+You will need to install those as well:
+
+```
+npm install  --no-optional --save-dev react-responsive@^5.0.0
+```
+
+Further reading: [Stack Overflow](https://stackoverflow.com/questions/46602286/npm-requires-a-peer-of-but-all-peers-are-in-package-json-and-node-modules)
+
+
 ## Publishing to GitHub Pages
 You can publish the GUI to github.io so that others on the Internet can view it.
 [Read the wiki for a step-by-step guide.](https://github.com/LLK/scratch-gui/wiki/Publishing-to-GitHub-Pages)