From 5c3c95a96cf09f3f25605e1d7b8796b644c75ac4 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Fri, 9 Feb 2018 19:36:00 +0000
Subject: [PATCH] docs: Mention G_ENABLE_DIAGNOSTIC in the porting notes

Since part of our type system is resolved at run time, we need to use
run time facilities to get diagnostic messages, like deprecation
warnings for properties and signals.

We should mention the G_ENABLE_DIAGNOSTIC environment variable in the
migration guide, to let developers know how to catch deprecations and
changes while porting their code.
---
 docs/reference/gtk/migrating-3to4.xml | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/docs/reference/gtk/migrating-3to4.xml b/docs/reference/gtk/migrating-3to4.xml
index ef6fa58e01..46327e43af 100644
--- a/docs/reference/gtk/migrating-3to4.xml
+++ b/docs/reference/gtk/migrating-3to4.xml
@@ -52,6 +52,21 @@
       </para>
     </section>
 
+    <section>
+      <title>Enable diagnostic warnings</title>
+      <para>
+        Deprecations of properties and signals cannot be caught at compile
+        time, as both properties and signals are installed and used after
+        types have been instantiated. In order to catch deprecations and
+        changes in the run time components, you should use the
+        <envar>G_ENABLE_DIAGNOSTIC</envar> environment variable when
+        running your application, e.g.:
+        <programlisting>
+          G_ENABLE_DIAGNOSTIC=1 ./your-app
+        </programlisting>
+      </para>
+    </section>
+
     <section>
       <title>Do not use widget style properties</title>
       <para>