mirror of
https://github.com/pacnpal/django-anymail.git
synced 2025-12-20 03:41:05 -05:00
Docs: 2.0 upgrade guide, release notes
This commit is contained in:
medmunds
@@ -20,6 +20,11 @@ Djrill: Mandrill Transactional Email for Django
|
||||
Djrill integrates the `Mandrill <http://mandrill.com>`_ transactional
|
||||
email service into Django.
|
||||
|
||||
**UPGRADING FROM DJRILL 1.x?**
|
||||
There are some **breaking changes in Djrill 2.0**. Please see the
|
||||
`upgrade instructions <http://djrill.readthedocs.org/en/latest/upgrading/>`_.
|
||||
|
||||
|
||||
In general, Djrill "just works" with Django's built-in `django.core.mail`
|
||||
package. It includes:
|
||||
|
||||
|
||||
106
docs/history.rst
106
docs/history.rst
@@ -1,3 +1,5 @@
|
||||
.. _history:
|
||||
|
||||
Release Notes
|
||||
=============
|
||||
|
||||
@@ -8,104 +10,28 @@ and breaking changes will always increment the
|
||||
major version number (1.x to 2.0).
|
||||
|
||||
|
||||
Djrill 2.0 (in development)
|
||||
---------------------------
|
||||
Djrill 2.x
|
||||
----------
|
||||
|
||||
Djrill 2.0 is under development and includes some breaking changes.
|
||||
Although the changes won't impact most Djrill users, the previous
|
||||
version of Djrill (1.4) tries to warn you if you use things
|
||||
that will change. (Warnings appear in the console when running Django
|
||||
in debug mode.)
|
||||
|
||||
|
||||
Breaking Changes in Djrill 2.0
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Dropped support for Django 1.3, Python 2.6, and Python 3.2
|
||||
Although Djrill may still work with these older configurations,
|
||||
we no longer test against them. Djrill now requires Django 1.4
|
||||
or later and Python 2.7, 3.3, or 3.4.
|
||||
|
||||
If you require earlier support, Djrill 1.4 remains available.
|
||||
|
||||
Removed DjrillAdminSite
|
||||
Earlier versions of Djrill included a custom Django admin site.
|
||||
The equivalent functionality is available in Mandrill's dashboard.
|
||||
|
||||
You should remove any references to DjrillAdminSite from your
|
||||
:file:`urls.py`. E.g.::
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Remove these:
|
||||
from djrill import DjrillAdminSite
|
||||
admin.site = DjrillAdminSite()
|
||||
|
||||
Also, on Django 1.7 or later if you had switched your :setting:`INSTALLED_APPS`
|
||||
(in :file:`settings.py`) to use ``'django.contrib.admin.apps.SimpleAdminConfig'``
|
||||
you *may* want to switch back to the default ``'django.contrib.admin'``
|
||||
and remove the call to ``admin.autodiscover()`` in your :file:`urls.py`.
|
||||
(Do this only if you changed to SimpleAdminConfig for Djrill, and aren't
|
||||
creating custom admin sites for any other Django apps you use.)
|
||||
|
||||
Added exception for invalid or rejected recipients
|
||||
Djrill 2.0 raises a new :exc:`djrill.MandrillRecipientsRefused` exception when
|
||||
all recipients of a message invalid or rejected by Mandrill. This parallels
|
||||
the behavior of Django's default :setting:`SMTP email backend <EMAIL_BACKEND>`,
|
||||
which raises :exc:`SMTPRecipientsRefused <smtplib.SMTPRecipientsRefused>` when
|
||||
all recipients are refused.
|
||||
|
||||
Your email-sending code should handle this exception (along with other
|
||||
exceptions that could occur during a send). However, if you want to retain the
|
||||
Djrill 1.x behavior and treat invalid or rejected recipients as successful sends,
|
||||
you can set :setting:`MANDRILL_IGNORE_RECIPIENT_STATUS` to ``True`` in your settings.py.
|
||||
|
||||
Removed unintended date-to-string conversion
|
||||
If your code was relying on Djrill to automatically convert date or datetime
|
||||
values to strings in :attr:`merge_vars`, :attr:`metadata`, or other Mandrill
|
||||
message attributes, you must now explicitly do the string conversion
|
||||
yourself. See :ref:`formatting-merge-data` for an explanation.
|
||||
(Djrill 1.4 reported a DeprecationWarning for this case.)
|
||||
|
||||
(The exception is :attr:`send_at`, which Djrill expects can be a date or
|
||||
datetime.)
|
||||
|
||||
Removed DjrillMessage class
|
||||
The ``DjrillMessage`` class has not been needed since Djrill 0.2.
|
||||
You should replace any uses of it with the standard
|
||||
:class:`~django.core.mail.EmailMessage` class.
|
||||
|
||||
Removed DjrillBackendHTTPError
|
||||
This exception was deprecated in Djrill 0.3. Replace uses of it
|
||||
with :exc:`djrill.MandrillAPIError`.
|
||||
|
||||
Refactored Djrill backend and exceptions
|
||||
Several internal details of ``djrill.mail.backends.DjrillBackend``
|
||||
and Djrill's exception classes have been significantly updated for 2.0.
|
||||
The intent is to make it easier to maintain and extend the backend
|
||||
(including creating your own subclasses to override Djrill's default
|
||||
behavior). As a result, though, any existing code that depended on
|
||||
undocumented Djrill internals may need to be updated.
|
||||
|
||||
|
||||
Other Djrill 2.0 Changes
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* Add Django 1.9 support; drop Django 1.3, Python 2.6, and Python 3.2
|
||||
Version 2.0:
|
||||
|
||||
* **Breaking Changes:** please see the :ref:`upgrade guide <upgrading>`.
|
||||
* Add Django 1.9 support; drop Django 1.3, Python 2.6, and Python 3.2 support
|
||||
* Add global :setting:`MANDRILL_SETTINGS` dict that can provide defaults
|
||||
for most Djrill message options.
|
||||
* Add :exc:`djrill.NotSerializableForMandrillError`
|
||||
* Use a single HTTP connection to the Mandrill API to improve performance
|
||||
when sending multiple messages at once using :func:`~django.core.mail.send_mass_mail`.
|
||||
(You can also directly manage your own long-lived Djrill connection across multiple sends,
|
||||
by calling open and close on :ref:`Django's email backend <django:topic-email-backends>`.)
|
||||
|
||||
* Add global :setting:`MANDRILL_SETTINGS` dict that can provide defaults
|
||||
for most Djrill message options.
|
||||
|
||||
* Add :exc:`djrill.NotSerializableForMandrillError`
|
||||
* Remove DjrillAdminSite
|
||||
* Remove unintended date-to-string conversion in JSON encoding
|
||||
* Remove obsolete DjrillMessage class and DjrillBackendHTTPError
|
||||
* Refactor Djrill backend and exceptions
|
||||
|
||||
|
||||
Older Releases
|
||||
--------------
|
||||
Djrill 1.x and Earlier
|
||||
----------------------
|
||||
|
||||
Version 1.4:
|
||||
|
||||
|
||||
@@ -23,6 +23,7 @@ Documentation
|
||||
|
||||
quickstart
|
||||
installation
|
||||
upgrading
|
||||
usage/sending_mail
|
||||
usage/templates
|
||||
usage/multiple_backends
|
||||
|
||||
121
docs/upgrading.rst
Normal file
121
docs/upgrading.rst
Normal file
@@ -0,0 +1,121 @@
|
||||
.. _upgrading:
|
||||
|
||||
Upgrading from 1.x
|
||||
==================
|
||||
|
||||
Djrill 2.0 includes some breaking changes from 1.x.
|
||||
These changes should have minimal (or no) impact on most Djrill users,
|
||||
but if you are upgrading please review the major topics below
|
||||
to see if they apply to you.
|
||||
|
||||
Djrill 1.4 tried to warn you if you were using Djrill features
|
||||
expected to change in 2.0. If you are seeing any deprecation warnings
|
||||
with Djrill 1.4, you should fix them before upgrading to 2.0.
|
||||
(Warnings appear in the console when running Django in debug mode.)
|
||||
|
||||
Please see the :ref:`release notes <history>` for a list of new features
|
||||
and improvements in Djrill 2.0.
|
||||
|
||||
|
||||
Dropped support for Django 1.3, Python 2.6, and Python 3.2
|
||||
----------------------------------------------------------
|
||||
|
||||
Although Djrill may still work with these older configurations,
|
||||
we no longer test against them. Djrill now requires Django 1.4
|
||||
or later and Python 2.7, 3.3, or 3.4.
|
||||
|
||||
If you require support for these earlier versions, you should
|
||||
not upgrade to Djrill 2.0. Djrill 1.4 remains available on
|
||||
pypi, and will continue to receive security fixes.
|
||||
|
||||
|
||||
Removed DjrillAdminSite
|
||||
-----------------------
|
||||
|
||||
Earlier versions of Djrill included a custom Django admin site.
|
||||
The equivalent functionality is available in Mandrill's dashboard,
|
||||
and Djrill 2.0 drops support for it.
|
||||
|
||||
Although most Djrill users were unaware the admin site existed,
|
||||
many did follow the earlier versions' instructions to enable it.
|
||||
|
||||
If you have added DjrillAdminSite, you will need to remove it for Djrill 2.0.
|
||||
|
||||
In your :file:`urls.py`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from djrill import DjrillAdminSite # REMOVE this
|
||||
admin.site = DjrillAdminSite() # REMOVE this
|
||||
|
||||
admin.autodiscover() # REMOVE this if you added it only for Djrill
|
||||
|
||||
In your :file:`settings.py`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
INSTALLED_APPS = (
|
||||
...
|
||||
# If you added SimpleAdminConfig only for Djrill:
|
||||
'django.contrib.admin.apps.SimpleAdminConfig', # REMOVE this
|
||||
'django.contrib.admin', # ADD this default back
|
||||
...
|
||||
)
|
||||
|
||||
(These instructions assume you had changed to SimpleAdminConfig
|
||||
solely for DjrillAdminSite. If you are using it for custom admin
|
||||
sites with any other Django apps you use, you should leave it
|
||||
SimpleAdminConfig in place, but still remove the references to
|
||||
DjrillAdminSite.)
|
||||
|
||||
|
||||
Added exception for invalid or rejected recipients
|
||||
--------------------------------------------------
|
||||
|
||||
Djrill 2.0 raises a new :exc:`djrill.MandrillRecipientsRefused` exception when
|
||||
all recipients of a message are invalid or rejected by Mandrill. (This parallels
|
||||
the behavior of Django's default :setting:`SMTP email backend <EMAIL_BACKEND>`,
|
||||
which raises :exc:`SMTPRecipientsRefused <smtplib.SMTPRecipientsRefused>` when
|
||||
all recipients are refused.)
|
||||
|
||||
Your email-sending code should handle this exception (along with other
|
||||
exceptions that could occur during a send). However, if you want to retain the
|
||||
Djrill 1.x behavior and treat invalid or rejected recipients as successful sends,
|
||||
you can set :setting:`MANDRILL_IGNORE_RECIPIENT_STATUS` to ``True`` in your settings.py.
|
||||
|
||||
|
||||
Other 2.0 breaking changes
|
||||
--------------------------
|
||||
|
||||
Code that will be affected by these changes is far less common than
|
||||
for the changes listed above, but they may impact some uses:
|
||||
|
||||
Removed unintended date-to-string conversion
|
||||
If your code was inadvertently relying on Djrill to automatically
|
||||
convert date or datetime values to strings in :attr:`merge_vars`,
|
||||
:attr:`metadata`, or other Mandrill message attributes, you must
|
||||
now explicitly do the string conversion yourself.
|
||||
See :ref:`formatting-merge-data` for an explanation.
|
||||
(Djrill 1.4 reported a DeprecationWarning for this case.)
|
||||
|
||||
(This does not affect :attr:`send_at`, where Djrill specifically
|
||||
allows date or datetime values.)
|
||||
|
||||
Removed DjrillMessage class
|
||||
The ``DjrillMessage`` class has not been needed since Djrill 0.2.
|
||||
You should replace any uses of it with the standard
|
||||
:class:`~django.core.mail.EmailMessage` class.
|
||||
(Djrill 1.4 reported a DeprecationWarning for this case.)
|
||||
|
||||
Removed DjrillBackendHTTPError
|
||||
This exception was deprecated in Djrill 0.3. Replace uses of it
|
||||
with :exc:`djrill.MandrillAPIError`.
|
||||
(Djrill 1.4 reported a DeprecationWarning for this case.)
|
||||
|
||||
Refactored Djrill backend and exceptions
|
||||
Several internal details of ``djrill.mail.backends.DjrillBackend``
|
||||
and Djrill's exception classes have been significantly updated for 2.0.
|
||||
The intent is to make it easier to maintain and extend the backend
|
||||
(including creating your own subclasses to override Djrill's default
|
||||
behavior). As a result, though, any existing code that depended on
|
||||
undocumented Djrill internals may need to be updated.
|
||||
Reference in New Issue
Block a user