Fix a bad setting naming about transaction scopes

Additionally give more explicit guidance about the setting.

Author: fredericDelaporte

doc/reference/modules/transactions.xml

@@ -644,16 +644,22 @@ finally
             <listitem>
                 <para>
                     As of NHibernate v5.0, <literal>FlushMode.Commit</literal> requires the configuration setting
-                    <literal>transaction.use_connection_on_system_events</literal> to be true for flushing
+                    <literal>transaction.use_connection_on_system_prepare</literal> to be true for flushing
                     from transaction scope commit. Otherwise, it will be your responsibility to flush the session
                     before completing the scope.
                 </para>
                 <para>
-                    Using <literal>transaction.use_connection_on_system_events</literal> can cause undesired
+                    Using <literal>transaction.use_connection_on_system_prepare</literal> can cause undesired
                     transaction promotions to distributed: it requires using a dedicated connection for flushing,
                     and it delays session disposal (if done inside the scope) to the scope disposal. If you want
                     to avoid this, set this setting to <literal>false</literal> and manually flush your sessions.
                 </para>
+                <para>
+                    For new applications, it is recommended to set
+                    <literal>transaction.use_connection_on_system_prepare</literal> to <literal>false</literal>,
+                    and to flush explicitly your sessions before scope completion. For old applications, consider
+                    checking how sessions are flushed, and if possible switch it to <literal>false</literal> too.
+                </para>
             </listitem>
             <listitem>
                 <para>
@@ -669,7 +675,7 @@ finally
                     <literal>Reconnect()</literal> before re-using the session.)
                 </para>
                 <para>
-                    When using <literal>transaction.use_connection_on_system_events</literal>, if the session is
+                    When using <literal>transaction.use_connection_on_system_prepare</literal>, if the session is
                     disposed within the scope, the connection releasing will still occurs from transaction
                     completion event.
                 </para>
@@ -678,7 +684,7 @@ finally
                 <para>
                     As of NHibernate v5.0, using transaction scope and trying to use the session connection within
                     <literal>AfterTransactionCompletion</literal> is forbidden and will raise an exception.
-                    If the setting <literal>transaction.use_connection_on_system_events</literal>
+                    If the setting <literal>transaction.use_connection_on_system_prepare</literal>
                     is <literal>false</literal>, it will forbid any connection usage from
                     <literal>BeforeTransactionCompletion</literal> event too, when this event is triggered by
                     a transaction scope commit or rollback.

releasenotes.txt

@@ -1,3 +1,12 @@
+Build 5.2.0
+=============================
+
+Release notes - NHibernate - Version 5.2.0
+
+
+As part of releasing 5.2.0, a misnamed setting in 5.0.0 release notes has been fixed:
+transaction.use_connection_on_system_events correct name is transaction.use_connection_on_system_prepare
+
 Build 5.1.3
 =============================
 
@@ -383,7 +392,7 @@ Build 5.0.0
         * Transaction scopes handling has undergone a major rework. See NH-4011 for full details.
           ** More transaction promotion to distributed may occur if you use the "flush on commit" feature with
              transaction scopes. Explicitly flush your session instead. Ensure it does not occur by disabling
-             transaction.use_connection_on_system_events setting.
+             transaction.use_connection_on_system_prepare setting.
           ** After transaction events no more allow using the connection when they are raised from a scope
              completion.
           ** Connection enlistment in an ambient transaction is now enforced by NHibernate by default.