--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/3.19.rst	Mon Jan 13 15:56:52 2014 +0100
@@ -0,0 +1,142 @@
+What's new in CubicWeb 4.0?
+============================
+
+Behavior Changes
+----------------
+
+* The anonymous property of Session and Connection are now computed from the
+  related user login. If it match the ``anonymous-user`` in the config the
+  connection is anonymous. Beware that the ``anonymous-user`` config is web
+  specific. Therefore, no session may be anonymous in repository only setup.
+
+New Repository Access API
+-------------------------
+
+Connection replace Session
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A new explicite Connection object replace Session as the main repository entry
+point. Connection hold all the necessary methods to be used Server side
+(``execute``, ``commit``, ``rollback``, ``call_service``, ``entity_from_eid``,
+etc…). You obtains a new Connection object using ``session.new_cnx()``.
+Connection object need have an explicite begin and end. Use them as a context
+manager::
+
+    with session.new_cnx() as cnx:
+        self.execute('INSERT Elephant E, E name "Cabar"')
+        self.commit()
+        self.execute('INSERT Elephant E, E name "Celeste"')
+        self.commit()
+    # Once you get out of the "with" clause, the connection is closed.
+
+Using the same Connection object in multiple threads will give you access to the
+same Transaction. However, Connection object are not thread safe.
+
+``repository.internal_session`` is deprecated in favor of
+``repository.internal_cnx``. Note that internal connection are now safe.
+Integrity hooks are enabled.
+
+Backward compact is preserved on Session. They can still be used to access the
+database for the next few version.
+
+dbapi vs repoapi
+~~~~~~~~~~~~~~~~
+
+A new API have been introduced to replace the dbapi. It is called "repoapi".
+
+there is three relevant function for now:
+
+``repoapi.get_repository(config)`` takes a config object and return credential
+
+``repoapi.connect(repo, **credential)`` return a ClientConnection associated to
+the user identified by the credential. The ClientConnection is associated to its
+own Session that is closed when the ClientConnection is closed. A
+ClientConnection is a Connection-like object to be used client side.
+
+``repoapi.anonymous_cnx(repo)`` return a ClientConnection associated to the
+anonymous user if describe in the Config.
+
+repoapi.ClientConnection replace dbapi.Connection and company
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On the client/web side, the Request is now using a ``repoapi.ClientConnection``
+instead of a ``dbapi.connection``. The ``ClientConnection`` have multiple backward
+compat method to looks like a ``dbapi.Cursor`` and ``dbapi.Connection``. It will
+remain that way for a few version.
+
+Session used on the Web side are now the same than the one used Server side.
+Some backward compat method have been installed on the server side Session to
+ease the transition.
+
+The authentification stack have been altered to use the ``repoapi`` instead of
+the ``dbapi``. Cubes adding new element in this stack are likely to break.
+
+New API in test
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All current methods and attributes used to access the repo on ``CubicwebTC`` are
+deprecated. You can now use a ``RepoAccess`` object. A ``RepoAccess`` object is
+linked to a new ``Session`` for a specified user. It is able to create
+``Connection``, ``ClientConnection`` and web side request linked to this
+session::
+
+    access =self.new_access("babar") # create a new RepoAccess for user babar
+    with access.repo_cnx() as cnx:
+        # some work with server side cnx
+        cnx.execute(…)
+        cnx.commit()
+        cnx.execute(…)
+        cnx.commit()
+
+    with access.client_cnx() as cnx:
+        # some work with client side cnx
+        cnx.execute(…)
+        cnx.commit()
+
+    with access.web_request(elephant="babar") as req:
+        # some work with client side cnx
+        elephant_name = req.form["elephant"]
+        req.execute(…)
+        req.cnx.commit()
+
+By default ``testcase.admin_access`` contains a ``RepoAccess`` object for the
+default admin session.
+
+
+API changes
+-----------
+
+* ``RepositorySessionManager.postlogin`` is now called with two arguments,
+  request and session. And this now happens before the session is linked to the
+  request.
+
+* ``SessionManager`` and ``AuthenticationManager`` now take a repo object at
+  initialization time instead of a vreg.
+
+* The ``async`` argument of ``_cw.call_service`` have been dropped. All call are
+  now  synchronous. The zmq notification bus looks like a good replacement for
+  most async usecase.
+
+* ``repo.stats()`` is now deprecated. The same information are available through
+  a service (``_cw.call_service('repo_stats')``)
+
+* ``repo.gc_stats()`` is now deprecated. The same information are available through
+  a service (``_cw.call_service('repo_gc_stats')``)
+
+* ``request.set_session`` no longer takes an optional ``user`` argument.
+
+* CubicwebTC does not have repo and cnx as class attributes anymore. They are
+  standard instance attributes. ``set_cnx`` and ``_init_repo`` class methods
+  become instance methods.
+
+* ``set_cnxset`` and ``free_cnxset`` are deprecated. cnxset are now
+  automatically managed.
+
+
+Deprecated Code Drops
+----------------------
+
+* The ldapuser source has been dropped. ldapfeed is the only official source
+  remaining for ldap.
+
+* session.hijack_user mechanism has been dropped.