DevelopmentGuide.md in ddtrace-0.46.0

- old
+ new
@@ -112,9 +112,37 @@
 
 Because you are likely not running all tests locally, your report will contain partial coverage results.
 You *must* check the CI step `coverage` for the complete test coverage report, ensuring coverage is not
 decreased.
 
+**Ensuring tests don't leak resources**
+
+Tests execution can create resources that are hard to track: threads, sockets, files, etc. Because these resources can come
+from the both the test setup as well as the code under test, making sure all resources are properly disposed is important
+to prevent the application from inadvertently creating cumulative resources during its execution.
+
+When running tests that utilize threads, you might see an error message similar to this one:
+
+```
+Test leaked 1 thread: "Datadog::Workers::AsyncTransport integration tests"
+Ensure all threads are terminated when test finishes:
+1: #<Thread:0x00007fcbc99863d0 /Users/marco.costa/work/dd-trace-rb/spec/spec_helper.rb:145 sleep> (Thread)
+Thread Creation Site:
+        ./dd-trace-rb/spec/ddtrace/workers_integration_spec.rb:245:in 'new'
+        ./dd-trace-rb/spec/ddtrace/workers_integration_spec.rb:245:in 'block (4 levels) in <top (required)>'
+Thread Backtrace:
+        ./dd-trace-rb/spec/ddtrace/workers_integration_spec.rb:262:in 'sleep'
+        .dd-trace-rb/spec/ddtrace/workers_integration_spec.rb:262:in 'block (5 levels) in <top (required)>'
+        ./dd-trace-rb/spec/spec_helper.rb:147:in 'block in initialize'
+```
+
+This means that this test did not finish all threads by the time the test had finished. In this case, the thread
+creation can be traced to `workers_integration_spec.rb:245:in 'new'`. The thread itself is sleeping at `workers_integration_spec.rb:262:in 'sleep'`.
+
+The actionable in this case would be to ensure that the thread created in `workers_integration_spec.rb:245` is properly terminated by invoking `Thread#join` during the test tear down, which will wait for the thread to finish before returning.
+
+Depending on the situation, the thread in question might need to be forced to terminate. It's recommended to have a mechanism in place to terminate it (a shared variable that changes value when the thread should exit), but as a last resort, `Thread#terminate` forces the thread to finish. Keep in mind that regardless of the termination method, `Thread#join` must be called to ensure that the thread has completely finished its shutdown process.
+
 ### Checking code quality
 
 **Linting**
 
 The trace library uses Rubocop to enforce [code style](https://github.com/bbatsov/ruby-style-guide) and quality. To check, run: