NH-4000 - Prepare release of v5.0

* Set version to 5.0.0
* Update release notes
* Obsolete fixes in documentation
* Wording fixes in code documentation

Author: fredericDelaporte

build-common/NHibernate.props

@@ -3,7 +3,7 @@
     <VersionMajor Condition="'$(VersionMajor)' == ''">5</VersionMajor>
     <VersionMinor Condition="'$(VersionMinor)' == ''">0</VersionMinor>
     <VersionPatch Condition="'$(VersionPatch)' == ''">0</VersionPatch>
-    <VersionSuffix Condition="'$(VersionSuffix)' == ''">Alpha1</VersionSuffix>
+    <VersionSuffix Condition="'$(VersionSuffix)' == ''"></VersionSuffix>
 
     <VersionPrefix>$(VersionMajor).$(VersionMinor).$(VersionPatch)</VersionPrefix>
     <AssemblyVersion>$(VersionMajor).$(VersionMinor).0.0</AssemblyVersion>

build-common/common.xml

@@ -35,7 +35,7 @@
 
 	<!-- This is used only for build folder -->
 	<!-- TODO: Either remove or refactor to use NHibernate.props -->
-	<property name="project.version" value="5.0.0-Alpha1" overwrite="false" />
+	<property name="project.version" value="5.0.0" overwrite="false" />
 	<property name="project.version.numeric" value="5.0.0" overwrite="false" />
 
 	<!-- debug|release -->

default.build

@@ -190,8 +190,11 @@
 		</copy>
 		<copy todir="${bin-pack.required}">
 			<fileset basedir="${bin.dir}">
+				<include name="Antlr3.Runtime.???" />
 				<include name="Iesi.Collections.???" />
 				<include name="NHibernate.???" />
+				<include name="Remotion.Linq.???" />
+				<include name="Remotion.Linq.EagerFetching.???" />
 			</fileset>
 		</copy>
 		<!--Required Bins for lazy loading NHibernate.ByteCode.Castle.dll-->

doc/reference/modules/architecture.xml

@@ -132,8 +132,8 @@
                     <listitem>
                         <para>
                             (Optional) A factory for ADO.NET connections and commands. Abstracts application
-                            from the concrete vendor-specific implementations of <literal>IDbConnection</literal>
-                            and <literal>IDbCommand</literal>. Not exposed to application, but can be
+                            from the concrete vendor-specific implementations of <literal>DbConnection</literal>
+                            and <literal>DbCommand</literal>. Not exposed to application, but can be
                             extended/implemented by the developer.
                         </para>
                     </listitem>

doc/reference/modules/basic_mapping.xml

@@ -106,9 +106,8 @@
                      <area id="hm5" coords="6 55"/>
                    <area id="hm6" coords="7 55"/>
                    <area id="hm7" coords="8 55"/>
-                 </areaspec>   
-                 <programlisting>
-           <![CDATA[<hibernate-mapping
+                 </areaspec>
+                 <programlisting><![CDATA[<hibernate-mapping
          schema="schemaName"
          default-cascade="none|save-update"
          auto-import="true|false"
@@ -681,7 +680,7 @@
 
                 <para>
                     Unfortunately, you can't use <literal>hilo</literal> when supplying your own
-                    <literal>IDbConnection</literal> to NHibernate. NHibernate must be able to
+                    <literal>DbConnection</literal> to NHibernate. NHibernate must be able to
                     fetch the "hi" value in a new transaction.
                 </para>
             </sect3>
@@ -1198,9 +1197,11 @@
             </programlistingco>
 
             <para>
-                Version numbers may be of type <literal>Int64</literal>, <literal>Int32</literal>,
+                Version may be of type <literal>Int64</literal>, <literal>Int32</literal>,
                 <literal>Int16</literal>, <literal>Ticks</literal>, <literal>Timestamp</literal>,
-                or <literal>TimeSpan</literal> (or their nullable counterparts in .NET 2.0).
+                <literal>TimeSpan</literal>, <literal>datetimeoffset</literal>, ... (or their nullable
+                counterparts in .NET 2.0). Any type implementing <literal>IVersionType</literal> is
+                usable as a version.
             </para>
 
         </sect2>
@@ -1433,7 +1434,11 @@
                 attribute. (For example, to distinguish between <literal>NHibernateUtil.DateTime</literal> and
                 <literal>NHibernateUtil.Timestamp</literal>, or to specify a custom type.)
             </para>
-            
+
+            <para>
+                See also <xref linkend="mapping-types" />.
+            </para>
+
             <para>
                 The <literal>access</literal> attribute lets you control how NHibernate will access
                 the value of the property at runtime.  The value of the <literal>access</literal> attribute should
@@ -2584,8 +2589,10 @@
             <para>
                 The <emphasis>basic types</emphasis> may be roughly categorized into three groups - <literal>System.ValueType</literal>
                 types, <literal>System.Object</literal> types, and <literal>System.Object</literal> types for large objects.  Just like
-                the .NET Types, columns for System.ValueType types <emphasis>can not</emphasis> store <literal>null</literal> values
-                and System.Object types	<emphasis>can</emphasis> store <literal>null</literal> values.
+                Columns for System.ValueType types can handle <literal>null</literal> values only if the entity property is properly
+                typed with a <literal>Nullable&lt;T&gt;</literal>. Otherwise <literal>null</literal> will be replaced by the default
+                value for the type when reading, and when be overwritten by it when persisting the entity, potentially leading to
+                phantom updates.
             </para>
             <table>
                 <title>System.ValueType Mapping Types</title>
@@ -2643,7 +2650,7 @@
                             </entry>
                             <entry>
                                 Default when no <literal>type</literal> attribute specified. Does no
-                                more ignore milliseconds since NHibernate v5.0.
+                                longer ignore fractional seconds since NHibernate v5.0.
                             </entry>
                         </row>
                         <row>
@@ -2652,7 +2659,10 @@
                             <entry>
                                 <literal>DbType.DateTime</literal> / <literal>DbType.DateTime2</literal><coref linkend="basic_mapping.datetime-co" />
                             </entry>
-                            <entry><literal>type="DateTimeNoMs"</literal> must be specified. Ignores milliseconds.</entry>
+                            <entry>
+                                <literal>type="DateTimeNoMs"</literal> must be specified. Ignores fractional seconds.
+                                Available since NHibernate v5.0.
+                            </entry>
                         </row>
                         <row>
                             <entry><literal>DateTime2</literal></entry>
@@ -2727,7 +2737,7 @@
                                 <literal>type="LocalDateTime"</literal> must be specified. Ensures the
                                 <literal>DateTimeKind</literal> is set to <literal>DateTimeKind.Local</literal>.
                                 Throws if set with a date having another kind.
-                                Does no more ignore milliseconds since NHibernate v5.0.
+                                Does no longer ignore fractional seconds since NHibernate v5.0.
                             </entry>
                         </row>
                         <row>
@@ -2738,7 +2748,8 @@
                             </entry>
                             <entry>
                                 <literal>type="LocalDateTimeNoMs"</literal> must be specified. Similar to
-                                <literal>type="LocalDateTime"</literal> but ignores milliseconds.
+                                <literal>LocalDateTime</literal> but ignores fractional seconds.
+                                Available since NHibernate v5.0.
                             </entry>
                         </row>
                         <row>
@@ -2829,7 +2840,7 @@
                             <entry>
                                 Ensures the <literal>DateTimeKind</literal> is set to <literal>DateTimeKind.Utc</literal>.
                                 Throws if set with a date having another kind.
-                                Does no more ignore milliseconds since NHibernate v5.0.
+                                Does no longer ignore fractional seconds since NHibernate v5.0.
                             </entry>
                         </row>
                         <row>
@@ -2840,7 +2851,8 @@
                             </entry>
                             <entry>
                                 <literal>type="UtcDateTimeNoMs"</literal> must be specified. Similar to
-                                <literal>type="LocalDateTime"</literal> but ignores milliseconds.
+                                <literal>UtcDateTime</literal> but ignores fractional seconds.
+                                Available since NHibernate v5.0.
                             </entry>
                         </row>
                         <row>
@@ -3251,7 +3263,7 @@
             NHibernate's schema evolution tools, to provide the ability to fully define
             a user schema within the NHibernate mapping files.  Although designed specifically
             for creating and dropping things like triggers or stored procedures, really any
-            SQL command that can be run via a <literal>IDbCommand.ExecuteNonQuery()</literal>
+            SQL command that can be run via a <literal>DbCommand.ExecuteNonQuery()</literal>
             method is valid here (ALTERs, INSERTS, etc).  There are essentially two modes for
             defining auxiliary database objects.
         </para>

doc/reference/modules/configuration.xml

@@ -115,8 +115,8 @@ Configuration cfg = new Configuration()
             obtain ADO.NET connections wherever it pleases:
         </para>
 
-        <programlisting><![CDATA[IDbConnection conn = myApp.GetOpenConnection();
-ISession session = sessions.OpenSession(conn);
+        <programlisting><![CDATA[var conn = myApp.GetOpenConnection();
+var session = sessions.OpenSession(conn);
 
 // do some data access work]]></programlisting>
 
@@ -291,7 +291,7 @@ ISession session = sessions.OpenSession(conn);
                     <literal>command_timeout</literal>
                 </entry>
                 <entry>
-                    Specify the default timeout of <literal>IDbCommands</literal>
+                    Specify the default timeout of <literal>DbCommand</literal>s
                     generated by NHibernate.
                 </entry>
             </row>

doc/reference/modules/example_parentchild.xml

@@ -342,8 +342,7 @@ session.Flush();]]></programlisting>
              and <literal>OnSave()</literal> as follows.
          </para>
 
-         <programlisting>
-	<![CDATA[public object IsTransient(object entity)
+         <programlisting><![CDATA[public object IsTransient(object entity)
 {
     if (entity is Persistent)
     {

doc/reference/modules/manipulating_data.xml

@@ -160,7 +160,7 @@ var problems = sess
         <para>
             These given <literal>Set</literal> parameters are used to bind the given values to the
             <literal>?</literal> query placeholders (which map to input
-            parameters of an ADO.NET <literal>IDbCommand</literal>). Just
+            parameters of an ADO.NET <literal>DbCommand</literal>). Just
             as in ADO.NET, you should use this binding mechanism in preference to string
             manipulation.
         </para>

doc/reference/modules/query_linq.xml

@@ -428,15 +428,15 @@ using NHibernate.Linq;]]></programlisting>
       At that point, all defined future results are evaluated in one single round-trip to database.
     </para>
     <programlisting><![CDATA[// Define queries
-IEnumerable<Cat> cats =
+IFutureEnumerable<Cat> cats =
     session.Query<Cat>()
         .Where(c => c.Color == "black")
         .ToFuture();
 IFutureValue<int> catCount =
     session.Query<Cat>()
         .ToFutureValue(q => q.Count());
 // Execute them
-foreach(Cat cat in cats)
+foreach(Cat cat in cats.GetEnumerable())
 {
     // Do something
 }
@@ -447,7 +447,9 @@ if (catCount.Value > 10)
 ]]></programlisting>
     <para>
       In above example, accessing <literal>catCount.Value</literal> does not trigger a round-trip to database:
-      it has been evaluated with <literal>cats</literal> enumeration.
+      it has been evaluated with <literal>cats.GetEnumerable()</literal> call. If instead
+      <literal>catCount.Value</literal> was accessed first, it would have executed both future and
+      <literal>cats.GetEnumerable()</literal> would have not trigger a round-trip to database.
     </para>
   </sect1>
 
@@ -482,6 +484,7 @@ IList<Cat> oldCats =
     oldCatsQuery
         .FetchMany(c => c.AnotherCollection)
         .ToFuture()
+        .GetEnumerable()
         .ToList();]]></programlisting>
     <para>&nbsp;</para>
 

doc/reference/modules/query_queryover.xml

@@ -337,9 +337,9 @@ IList<CatSummary> catReport =
 
         <para>
             In addition to projecting properties, there are extension methods to allow certain common dialect-registered
-            functions to be applied.  For example you can write the following to extract just the year part of a date:
+            functions to be applied.  For example you can write the following to get 3 letters named people.
         </para>
-        <programlisting><![CDATA[        .Where(p => p.BirthDate.YearPart() == 1971)]]></programlisting>
+        <programlisting><![CDATA[        .Where(p => p.FirstName.StrLength() == 3)]]></programlisting>
 
         <para>
             The functions can also be used inside projections:

doc/reference/modules/query_sql.xml

@@ -588,7 +588,7 @@ var pusList = query.SetString("name", "Pus%").List<Cat>();]]></programlisting>
         <itemizedlist spacing="compact">
           <listitem>
             <para>The procedure must return a result set. NHibernate will
-            use <literal>IDbCommand.ExecuteReader()</literal> to obtain
+            use <literal>DbCommand.ExecuteReader()</literal> to obtain
             the results.
             </para>
           </listitem>
@@ -657,7 +657,7 @@ var pusList = query.SetString("name", "Pus%").List<Cat>();]]></programlisting>
 
     <para>The stored procedures are by default required to affect the same number
     of rows as NHibernate-generated SQL would. NHibernate uses
-    <literal>IDbCommand.ExecuteNonQuery</literal> to retrieve the number of rows
+    <literal>DbCommand.ExecuteNonQuery</literal> to retrieve the number of rows
     affected. This check can be disabled by using <literal>check="none"</literal>
     attribute in <literal>sql-insert</literal> element.
     </para>

doc/reference/modules/quickstart.xml

@@ -411,7 +411,7 @@ finally
             NHibernate also offers an object-oriented <emphasis>query by criteria</emphasis> API
             that can be used to formulate type-safe queries, and the Hibernate Query Language (HQL),
             which is an easy to learn and powerful object-oriented extension to SQL.
-            NHibernate of course uses <literal>IDbCommand</literal>s and parameter binding for all
+            NHibernate of course uses <literal>DbCommand</literal>s and parameter binding for all
             SQL communication with the database. You may also use NHibernate's direct SQL query
             feature or get a plain ADO.NET connection from an <literal>ISession</literal> in rare
             cases.