# HG changeset patch
# User Aurelien Campeas <aurelien.campeas@logilab.fr>
# Date 1245148440 -7200
# Node ID df86450ca65d5e4adb52c9e56da1da813ee6c0fd
# Parent  d7773fb1b892ae8830e27809bf3c960b3ebb9c6a
[doc] a note on sessions

diff -r d7773fb1b892 -r df86450ca65d doc/book/en/development/devrepo/sessions.rst
--- a/doc/book/en/development/devrepo/sessions.rst	Mon Jun 15 18:30:27 2009 +0200
+++ b/doc/book/en/development/devrepo/sessions.rst	Tue Jun 16 12:34:00 2009 +0200
@@ -3,7 +3,24 @@
 Sessions
 ========
 
+There are three kinds of sessions.
+
+* user sessions are the most common: they are related to users and
+  carry security checks coming with user credentials
+
+* super sessions are children of ordinary user sessions and allow to
+  bypass security checks (they are created by calling unsafe_execute
+  on a user session); this is often convenient in hooks which may
+  touch data that is not directly updatable by users
+
+* internal sessions have all the powers; they are also used in only a
+  few situations where you don't already have an adequate session at
+  hand, like: user authentication, data synchronisation in
+  multi-source contexts
+
+Do not confuse the session type with their connection mode, for
+instance : 'in memory' or 'pyro'.
+
 [WRITE ME]
 
 * authentication and management of sessions
-