pacnpal/django-anymail
1
0
Fork 0
mirror of https://github.com/pacnpal/django-anymail.git synced 2025-12-20 03:41:05 -05:00
Code Issues Packages Projects Releases Wiki Activity

Docs: 2.0 upgrade guide, release notes

Browse Source
This commit is contained in:
medmunds
2015-12-02 18:25:26 -08:00
parent c625b6f12f
commit 7706a5d39f
4 changed files with 143 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
README.rst
View File

@@ -20,6 +20,11 @@ Djrill: Mandrill Transactional Email for Django
Djrill integrates the `Mandrill <http://mandrill.com>`_ transactional Djrill integrates the `Mandrill <http://mandrill.com>`_ transactional
email service into Django. 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` In general, Djrill "just works" with Django's built-in `django.core.mail`
package. It includes: package. It includes:

106
docs/history.rst
View File

@@ -1,3 +1,5 @@
.. _history:
Release Notes Release Notes
============= =============
@@ -8,104 +10,28 @@ and breaking changes will always increment the
major version number (1.x to 2.0). 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. Version 2.0:
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
* **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 * 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`. 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, (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>`.) by calling open and close on :ref:`Django's email backend <django:topic-email-backends>`.)
* Remove DjrillAdminSite
* Add global :setting:`MANDRILL_SETTINGS` dict that can provide defaults * Remove unintended date-to-string conversion in JSON encoding
for most Djrill message options. * Remove obsolete DjrillMessage class and DjrillBackendHTTPError
* Refactor Djrill backend and exceptions
* Add :exc:`djrill.NotSerializableForMandrillError`
Older Releases Djrill 1.x and Earlier
-------------- ----------------------
Version 1.4: Version 1.4:

1
docs/index.rst
View File

@@ -23,6 +23,7 @@ Documentation
quickstart quickstart
installation installation
upgrading
usage/sending_mail usage/sending_mail
usage/templates usage/templates
usage/multiple_backends usage/multiple_backends

121
docs/upgrading.rst Normal file
View 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.