Start work on a "What's New" section

doc/sphinx/index.rst

@@ -37,6 +37,7 @@ Contents:
    tutorial/index.rst
    users-guide/index.rst
    reference/index.rst
+   whats-new/index.rst
    phk/index.rst
    glossary/index.rst
 

doc/sphinx/whats-new/changes.rst

+.. _whatsnew_changes:
+
+Changes in Varnish 4
+====================
+
+Varnish 4 is quite an extensive update over Varnish 3, with some very big improvements to central parts of varnish.
+
+Client/backend split
+--------------------
+In the past, Varnish has fetched the content from the backend in the same
+thread as the client request. The client and backend code has now been split,
+allowing for some much requested improvements.
+This split allows varnish to refresh content in the background while serving
+stale content quickly to the client.
+
+This split has also necessitated a change of the VCL-functions, in particular functionality has moved from the old vcl_fetch method to the two new methods vcl_backend_fetch and vcl_backend_response.

doc/sphinx/whats-new/index.rst

+.. _whats-new-index:
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%
+What's new for Varnish 4.0
+%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+This document describes the changes that have been made for Varnish 4. The
+first section will describe the overarching changes that have gone into
+Varnish, while the second section describes what changes you need to make to
+your configuration as well as any changes in behaviour that you need to take
+into consideration while upgrading.
+
+.. toctree::
+   :maxdepth: 2
+
+   changes
+   upgrading

doc/sphinx/whats-new/upgrading.rst

+.. _whatsnew_upgrading:
+
+%%%%%%%%%%%%%%%%%%%%%%
+Upgrading to Varnish 4
+%%%%%%%%%%%%%%%%%%%%%%
+
+Changes to VCL
+==============
+
+Much of the VCL syntax has changed in Varnish 4. We've tried to compile a list of changes needed to upgrade here.
+
+Version statement
+~~~~~~~~~~~~~~~~~
+To make sure that people have upgraded their VCL to the current version, varnish now requires the first line of VCL to indicate the VCL version number::
+
+	vcl 4.0;
+
+vcl_fetch is now vcl_backend_response
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Directors have been moved to the vmod_directors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use the hash director as a client director
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Since the client director was already a special case of the hash director, it has been removed, and you should use the hash director directly::
+
+	sub vcl_init {
+        	new h = directors.hash();
+        	h.add_backend(b1, 1);
+        	h.add_backend(b2, 1);
+	}
+	
+	sub vcl_recv {
+		set req.backend = h.backend(client.ip);
+	}
+
+error() is now a return value
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You must now explicitly return an error::
+
+	return(error(999, "Response));
+
+hit_for_pass objects are created using beresp.uncacheable
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Example::
+
+	sub vcl_backend_response {
+		if(beresp.http.X-No-Cache) {
+			set beresp.uncacheable = true;
+			set beresp.ttl = 120s;
+			return(deliver);
+		}
+	}
+
+vcl_recv should return(hash) instead of lookup now
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+req.* not available in vcl_backend_response
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+req.* used to be available in vcl_fetch, but after the split of functionality, you only have bereq.* in vcl_backend_response.
+
+vcl_* reserved
+~~~~~~~~~~~~~~
+Your own subs cannot be named vcl_* anymore. That is reserved for builtin subs.
+
+req.backend.healthy replaced by std.healthy(req.backend)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Changes to parameters
+=====================
+
+linger
+~~~~~~
+
+sess_timeout
+~~~~~~~~~~~~