Upgrading docs

docs/en/changelogs/4.0.0.md

@@ -0,0 +1,98 @@
+# 4.0.0 (unreleased)
+
+## Overview
+
+### Framework
+
+ * Deprecate `SQLQuery` in favour `SQLSelect`
+ * `DataList::filter` by null now internally generates "IS NULL" or "IS NOT NULL" conditions appropriately on queries
+ * `Controller::init` visibility changed to protected
+ * Initialising controllers now the responsibility of `Controller::doInit()`
+ * `handleRequest`
+
+## Upgrading
+
+### Update code that uses SQLQuery
+
+SQLQuery is still implemented, but now extends the new SQLSelect class and has some methods
+deprecated. Previously this class was used for both selecting and deleting, but these
+have been superceded by the specialised SQLSelect and SQLDelete classes.
+
+Take care for any code or functions which expect an object of type `SQLQuery`, as
+these references should be replaced with `SQLSelect`. Legacy code which generates
+`SQLQuery` can still communicate with new code that expects `SQLSelect` as it is a
+subclass of `SQLSelect`, but the inverse is not true.
+
+### Update implementations of augmentSQL
+
+Since this method now takes a `SQLSelect` as a first parameter, existing code referencing the deprecated `SQLQuery`
+type will raise a PHP error.
+
+E.g.
+
+Before:
+
+	:::php
+	function augmentSQL(SQLQuery &$query, DataQuery &$dataQuery = null) {
+		$locale = Translatable::get_current_locale();
+		if(!preg_match('/("|\'|`)Locale("|\'|`)/', implode(' ', $query->getWhere())))  {
+			$qry = sprintf('"Locale" = \'%s\'', Convert::raw2sql($locale));
+			$query->addWhere($qry); 
+		}
+	}
+
+After:
+
+	:::php
+	function augmentSQL(SQLSelect $query, DataQuery $dataQuery = null) {
+		$locale = Translatable::get_current_locale();
+		if(!preg_match('/("|\'|`)Locale("|\'|`)/', implode(' ', $query->getWhereParameterised($parameters))))  {
+			$query->addWhere(array(
+				'"Locale"' => $locale
+			));
+		}
+	}
+
+
+### Update to Controller initialisation
+
+`Controller::init` is now protected, so any overloaded instances of this method need to have their visibility changed to
+`protected`
+
+Before:
+
+	:::php
+	public function init() {
+		parent::init();
+		
+		if (!Member::currentMemberID()) {
+			Security::permissionFailure($this);
+		}
+	}
+
+After:
+
+	:::php
+	protected function init() {
+		parent::init();
+		
+		if (!Member::currentMemberID()) {
+			Security::permissionFailure($this);
+		}
+	}
+
+Initialising controllers now need to be done with the `doInit` method.
+
+Before:
+
+	:::php
+
+	$controller = ModelAsController::controller_for(Page::get()->first());
+	$controller->init();
+
+After:
+
+	:::php
+
+	$controller = ModelAsController::controller_for(Page::get()->first());
+	$controller->doInit();