Opened 5 years ago

Closed 4 years ago

#17026 closed Cleanup/optimization (fixed)

Message storage backends section missing "just use x"

Reported by: coolRR Owned by: Aymeric Augustin
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 5 years ago by Aymeric Augustin

Needs documentation: unset
Needs tests: unset
Patch needs improvement: unset
Summary: Docs section missing "just use x"Message storage backends section missing "just use x"
Triage Stage: UnreviewedAccepted

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

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

Resolution: fixed
Status: newclosed

In [03896eb5df74a47237ec3ed9a73aadc925e90dbb]:

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

comment:3 Changed 4 years ago by Aymeric Augustin

Resolution: fixed
Status: closedreopened
Version: 1.3master

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 4 years ago by Aymeric Augustin

Owner: changed from nobody to Aymeric Augustin
Status: reopenednew

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

Resolution: fixed
Status: newclosed

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