Opened 4 years ago

Closed 3 years ago

#17026 closed Cleanup/optimization (fixed)

Message storage backends section missing "just use x"

Reported by: coolRR Owned by: aaugustin
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no


This section:

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.

Change History (5)

comment:1 Changed 4 years ago by aaugustin

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Summary changed from Docs section missing "just use x" to Message storage backends section missing "just use x"
  • Triage Stage changed from Unreviewed to Accepted

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

comment:2 Changed 3 years ago by Claude Paroz <claude@…>

  • Resolution set to fixed
  • Status changed from new to closed

In [03896eb5df74a47237ec3ed9a73aadc925e90dbb]:

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

comment:3 Changed 3 years ago by aaugustin

  • Resolution fixed deleted
  • Status changed from closed to reopened
  • Version changed from 1.3 to master

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

comment:4 Changed 3 years ago by aaugustin

  • Owner changed from nobody to aaugustin
  • Status changed from reopened to new

comment:5 Changed 3 years ago by Aymeric Augustin <aymeric.augustin@…>

  • Resolution set to fixed
  • Status changed from new to closed

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).

Note: See TracTickets for help on using tickets.
Back to Top