MINOR: Updated upgrade guide.

docs/en/changelogs/alpha/3.0.0-alpha1.md

@@ -3,6 +3,7 @@
 ## Overview ##
 
  * New ORM: More flexible and expressive querying via `DataList`
+ * New ORM: Changes to manipulation of SQL queries
  * New ORM: Better encapsulation of relationship queries with `RelationList`
  * Early version of a `GridField` (formerly known as `DataGrid`) component which will supersede
 `ComplexTableField` and `TableListField`
@@ -11,6 +12,7 @@
  * User timezone support in `DateTimeField`
  * CMS UI: Collapsible menu, panel ajax loading with HTML5 history integration
  * CMS UI: New "add page" dialog
+ * Deprecation API
 
 See [3.0.0 upgrading guide](../3.0.0) for more details.
 
@@ -22,7 +24,7 @@ The new "fluent" syntax to retrieve ORM records allows for a more
 expressive notation (instead of unnamed arguments). 
 
 	// before
-	DataObject::get('Member', '"FirstName" = \'Sam'\', '"Surname" ASC")
+	DataObject::get('Member', '"FirstName" = \'Sam'\', '"Surname" ASC");
 	// after
 	DataList::create('Member')->filter(array('FirstName' => 'Sam'))->sort('Surname');
 	
@@ -31,13 +33,60 @@ lazy loading which fetches only the records it needs, as late as possible.
 In order to retrieve all ORM records manually (as the previous ORM would've done),
 please use `DataList->toArray()`.
 	
-	
 The old getters (`DataObject::get()`, `DataObject:;get_one()`, `DataObject::get_by_id()`)
 are now deprecated, but continue to operate. Instead of a `DataObjectSet`, they'll
 now return a `DataList`.
 
+	// before
+	DataObject::get_one('Member', '"Email" = \'someone@example.com\'');
+	// after
+	DataList::create('Member')->filter('Email', 'someone@example.com')->First();
+
+	// before
+	DataObject::get_by_id('Member', 5);
+	// after
+	DataList::create('Member')->byID(5);
+
+Note that they will return a `DataList` even if they're empty, so if you want to check 
+for the presence of records, please call the count() method on the `DataList`:
+
+	// before
+	if(!DataObject::get('SiteTree', '"ParentID" = 5')) echo "Page 5 has no children";
+	// after
+	if(!DataObject::get('SiteTree', '"ParentID" = 5')->count()) echo "Page 5 has no children";
+
 See the ["datamodel" documentation](../../topics/datamodel) for more details.
 
+### New ORM: Changes to manipulation of SQL queries ###
+
+In the 2.4 ORM it was sometimes necessary to bypass the ORM for performance reasons.  For example,
+this command would have been intolerably slow:
+
+	DataList::create('SiteTree')->count();
+	
+The 3.0 ORM is more intelligent gives you tools you need to create high-performance code without
+bypassing the ORM:
+
+	// before
+	echo DB::query("SELECT COUNT(*) FROM \"SiteTree\"")->value();
+	// after
+	echo DataList::create('SiteTree')->count()
+
+Both `extendedSQL()` and `buildSQL()` have been deprecated.  There is not currently any way of 
+overriding the query generation code equivalent to overriding `buildSQL()` in 2.4, but this facility
+was error prone.  If you need to access the `SQLQuery` object, you can call `->dataQuery()->query()`
+on any DataList.  Note that modifications to this query will **not** be passed back into the DataList.
+
+	// before
+	$query = singleton('SiteTree')->extendedSQL('ParentID = 5');
+	// after
+	$query = DataList::create('SiteTree')->filter('ParentID', 5)->dataQuery()->query();
+
+We advise that you keep this kind of code to a minimum and that you use the DataList wherever possible.
+If you find yourself needing to bypass the ORM in SilverStripe 3, we suggest you raise this
+as a discussion topic on silverstripe-dev@groups.google.com, as we may want to add more tools to
+the ORM to help you.
+
 ### New ORM: Better encapsulation of relationship queries with `RelationList` ###
 
 The abstract `RelationList` class and its implementations `ManyManyList` and `HasManyList`
@@ -61,6 +110,23 @@ As with any SilverStripe upgrade, we recommend database backups before calling `
 See [mysql.com](http://dev.mysql.com/doc/refman/5.5/en/converting-tables-to-innodb.html) for details on the conversion.
 Note: MySQL has made InnoDB the default engine in its [5.5 release](http://dev.mysql.com/doc/refman/5.5/en/innodb-storage-engine.html).
 
+### Deprecation API ###
+
+There is a new deprecation API that generates deprecation notices.  Calls to Deprecated methods
+will only produce errors if the API was deprecated in the release equal to or earlier than the
+"notification version".
+
+`sapphire/_config.php` currently contains a call to throw notices calls to all methods deprecated 
+in 3.0.
+
+	Deprecation::notification_version('3.0.0');
+	
+If you change the notification version to 3.0.0-dev, then only methods deprecated in older versions
+(e.g. 2.4) will trigger notices, and the other methods will silently pass.  This can be useful if
+you don't yet have time to remove all calls to deprecated methods.
+
+	Deprecation::notification_version('3.0.0-dev');
+
 ### Deprecated Classes and Methods ###
 
  * `FieldSet`: Use `FieldList` instead