added RDB info to docs

CONTRIBUTING.md

@@ -281,7 +281,7 @@ For feature work, take a look at the current [Enhancements](https://github.com/a
 
 If it has someone assigned to it then that person is the person responsible for working the enhancement. If you feel like you could contribute then reach out to that person.
 
-Fixing bugs, adding translations, and updating the documentation are always appreciated, so reviewing the backlog of issues is always a good place to start.
+Fixing bugs, adding translations, and updating the documentation are always appreciated, so reviewing the backlog of issues is always a good place to start. For extra information on debugging tools, see [Debugging](https://github.com/ansible/awx/blob/devel/docs/debugging.md).
 
 **NOTE**
 

docs/debugging.md

@@ -0,0 +1,50 @@
+Debugging
+=========
+
+
+
+Remote Debugging
+----------------
+Python processes in Tower's development environment are kept running in the
+background via supervisord.  As such, interacting with them via Python's
+standard `pdb.set_trace()` isn't possible.
+
+Bundled in our container environment is a remote debugging tool, `rdb`.  You
+can use it to set remote breakpoints in Tower code and debug interactively over
+a telnet session:
+
+```python
+    # awx/main/tasks.py
+
+    class SomeTask(awx.main.tasks.BaseTask):
+
+        def run(self, pk, **kwargs):
+            # This will set a breakpoint and open an interactive Python
+            # debugger exposed on a random port between 6899-6999.  The chosen
+            # port will be reported as a warning in the Tower logs, e.g.,
+            #
+            # [2017-01-30 22:26:04,366: WARNING/Worker-11] Remote Debugger:6900: Please telnet into 0.0.0.0 6900.
+            #
+            # You can access it from your host machine using telnet:
+            #
+            # $ telnet localhost <port>
+            import rdb
+            rdb.set_trace()
+```
+
+Keep in mind that when you interactively debug in this way, any process
+that encounters a breakpoint will wait until an active client is established
+(it won't handle additional tasks) and concludes the debugging session with
+a `continue` command.
+
+To simplify remote debugging session management, Tower's development
+environment comes with tooling that can automatically discover open
+remote debugging sessions and automatically connect to them.  From your *host*
+machine (i.e., _outside_ of the development container), you can run:
+
+```
+make rdb
+```
+
+This will open a Python process that listens for new debugger sessions and
+automatically connects to them for you.