Message storage backends section missing "just use x"

[Ram Rachum]

This section:

​https://docs.djangoproject.com/en/1.3/ref/contrib/messages/#storage-backends

Is missing a "just use x" sentence. As a new user I have no idea which storage backend is generally preferable. SessionStorage sounds best, but if FallbackStorage tries to use cookies but only then resorts to session, this leads me to believe that cookies are somehow better for messages than the session.

Please clarify.

[Aymeric Augustin]

Indeed, this section is a bit confusing, mostly because it describes complex backwards-compatibility code. It could use a better structure.

[Claude Paroz <claude@…>]

In [03896eb5df74a47237ec3ed9a73aadc925e90dbb]:

Fixed #17026 -- Improved wording of contrib.messages' storage backends section

[Aymeric Augustin]

I came across this section of the docs today (while debugging #18781) and thought "oh, what are the advantages and drawbacks of the three storage backends?".

So... I'd like to revisit this ticket.

The backends were introduced in [25020ddb05] as a consequence of #4604. The discussion on the ticket is quite long but there's a good summary on the SessionMessages wiki page. Notably it mentions the following requirement:

Use the session only as a fallback: Avoid database/cache queries if possible, but support larger messages that don't fit in a cookie (> 4kb) when needed

I think the docs should say something along the lines of:

• FallbackStorage optimizes for the general case by using cookies for small messages, and the session only when messages don't fit in a cookie. In general, there's no reason to use anything else.
• if your site doesn't use django.contrib.sessions, use CookieStorage
• if you have a good reason to keep your cookies minimal (hint: you probably don't), use SessionStorage

[Aymeric Augustin <aymeric.augustin@…>]

In [ce53a1d0bf51f59118569ec81e1a30b013bd352e]:

Clarified the messages documentation.

• Stated upfront that the messages framework is enabled by default.
• Explained why FallbackStorage, despites its unattractive name, is the default and likely the most efficient message storage class.

Thanks Jeremy Dunck for the review.

Closes #17026 (again).