From 5c91cd4cb45779fee8a0188ed49a0b6d79283a40 Mon Sep 17 00:00:00 2001
From: Bertrand Bordage <bordage.bertrand@gmail.com>
Date: Sun, 28 Sep 2014 01:45:02 +0200
Subject: [PATCH] Updates README.rst.

---
 README.rst | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 68 insertions(+), 4 deletions(-)

diff --git a/README.rst b/README.rst
index e7d3510..6f62de8 100644
--- a/README.rst
+++ b/README.rst
@@ -26,14 +26,78 @@ Usage
 #. Enjoy!
 
 
+Limits
+------
+
+Django-cachalot doesn’t cache queries it can’t reliably invalidate.
+If a SQL query or a part of it is written in pure SQL, it won’t be cached.
+
+That’s why ``QuerySet.extra`` with ``select`` or ``where`` arguments,
+``Model.objects.raw(…)``, & ``cursor.execute(…)`` queries are not cached.
+
+
+How django-cachalot works
+-------------------------
+
+**(If you don’t care/understand, just pretend it’s magic)**
+
+Reverse engineering
+...................
+
+It’s a lot of Django reverse engineering combined with a strong test suite.
+Such a test suite is crucial for a reverse engineering project.
+If some important part of Django changes and breaks the expected behaviour,
+you can be sure that the test suite will fail.
+
+Monkey patching
+...............
+
+django-cachalot modifies Django in place during execution to add a caching tool
+is added just before SQL queries are executed.
+We detect which cache keys must be removed when some data
+is created/changed/deleted on the database.
+
+
 What still needs to be done
 ---------------------------
 
-- Correctly invalidate ``.extra`` queries
+For version 1.0
+...............
+
 - Handle transactions
-- Handle multiple databases
-- Write tests, including multi-table inheritance, prefetch_related, etc
 - Find out if it’s thread-safe and test it
+- Write tests for `multi-table inheritance <https://docs.djangoproject.com/en/1.7/topics/db/models/#multi-table-inheritance>`_
+- Add support for other caches like memcached
+- Handle multiple databases
+- Add invalidation on migrations in Django 1.7 (& South?)
 - Add a ``CACHALOT_ENABLED`` setting
 - Add a setting to choose a cache other than ``'default'``
-- Add support for other caches like memcached
+- Use a continuous integration service to test against:
+
+  - Python 2.7, 3.3, & 3.4
+  - Django 1.6 & 1.7
+  - PostgreSQL, SQLite, & MySQL
+  - Redis, Memcached, LocMem
+
+In a more distant future
+........................
+
+- Parse queries using ``QuerySet.extra`` with ``select`` or ``where`` arguments
+  in order to find which tables are implied, and therefore be able
+  to cache them
+
+
+Legacy
+------
+
+This work is highly inspired of
+`johnny-cache <https://github.com/jmoiron/johnny-cache>`_, another easy-to-use
+ORM caching tool!  It’s working with Django <= 1.5.
+I used it in production during 3 years, it’s an excellent module!
+
+Unfortunately, we failed to make it migrate to Django 1.6 (I was involved).
+It was mostly because of the transaction system that was entirely refactored.
+
+I also noticed a few advanced invalidation issues when using ``QuerySet.extra``
+and some complex cases implying multi-table inheritance
+and related ``ManyToManyField``.