From 6292fa817f03d38fe13372a54d5b9ccd09103607 Mon Sep 17 00:00:00 2001
From: Karthik Nadig <karthik.nadig@live.com>
Date: Wed, 1 May 2019 18:27:56 -0700
Subject: [PATCH] Minor improvements to troubleshooting instructions (#1395)

* Minor improvements to troubleshooting instructions

* Address comments.
---
 TROUBLESHOOTING.md | 27 ++++++++++++++++++++++++---
 1 file changed, 24 insertions(+), 3 deletions(-)

diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
index e5adf18c..853e1b9d 100644
--- a/TROUBLESHOOTING.md
+++ b/TROUBLESHOOTING.md
@@ -7,9 +7,30 @@ in [Filing an issue](#filing-an-issue).
 ## Known Issues
 
 There are a few known issues in the current version of the debugger:
-- Multiprocess debugging on a Linux machine requires the `spawn` setting. See [#943](https://github.com/Microsoft/ptvsd/issues/943).
-- If you recieve an error saying  `breakpoint not set`, then look at your path mappings. See Meta-Issue [#2976](https://github.com/Microsoft/vscode-python/issues/2976) for more detail. 
-- If you want to debug library files, you have to enable `debugStdLib`. See [#1354](https://github.com/Microsoft/ptvsd/issues/1354).
+### 1. Multiprocessing on Linux/Mac
+ Multiprocess debugging on a Linux machine requires the `spawn` setting. We are working on improving this experience, see [#943](https://github.com/Microsoft/ptvsd/issues/943). Meanwhile do this to improve your debugging experience:
+```py
+import multiprocessing
+multiprocessing.set_start_method('spawn', True)
+```
+Note: On Windows, the `multiprocessing` package uses "spawn" as the default and only option, so it is recommended for cross-platform code to ensure uniform behavior. If you choose to use `spawn` you may have to structure your `__main__` module like this https://docs.python.org/3/library/multiprocessing.html#the-spawn-and-forkserver-start-methods.
+
+### 2. Breakpoints not set
+If you receive an error saying **breakpoint not set**, then look at your path mappings in `launch.json`. See Meta-Issue [#2976](https://github.com/Microsoft/vscode-python/issues/2976) for more details. 
+
+### 3. Debugging Library Files
+If you want to debug library files, you have to disable `justMyCode` in `launch.json`. Previously this setting was `debugStdLib`. For example:
+```js
+{
+    "name": "Terminal",
+    "type": "python",
+    "request": "launch",
+    "pythonPath": "${config:python.pythonPath}",
+    "program": "${file}",
+    "console": "integratedTerminal",
+    "justMyCode": false
+},
+```
 
 ## Filing an issue