*********************************************
Migrating from 1.3.4 to 1.3.5
*********************************************

.. warning::

    This guide has been updated because of `issue 480
    <https://github.com/devilry/devilry-django/issues/480>`_. The only change
    is a fourth step under :ref:`migrationguide1.3.5-update-settings`.

    If you have already completed the guide, but failed at the email settings step:

    1. Stop supervisord.
    2. Perform all changes in :ref:`migrationguide1.3.5-update-settings`.
    3. Start supervisord.
    4. Test that email is working as described in the last section of this guide.


Changes
=======
Bugfixes:

- https://github.com/devilry/devilry-django/issues/477
- https://github.com/devilry/devilry-django/issues/478


The most significant change is `django-celery-email <https://github.com/devilry/devilry-django/issues/477>`_ as email backend.

``django-celery-email`` sends all email into the Celery task queue, which then
sends email in the background one at a time. This fixes scalibility problems
when adding feedback in bulk. The issue that triggered this change was
https://github.com/devilry/devilry-django/issues/477.


Backup database and files
=========================
BACKUP. YOUR. DATABASE. AND. FILES.


Update devilry
==============

Move your logdir buildout config
--------------------------------
Previous versions of ``devilry-deploy`` defined the ``logdir`` in the
``[supervisor]``-section of ``buildout.cfg``. This has been moved to
``[variables]``. You should end up with something like this::

    [variables]
    logdir = /var/log/devilry



Update to v1.3.5 - but do not restart supervisord
-------------------------------------------------
Update ``REVISION`` to ``v1.3.5`` using the instructions in the :ref:`update guide <update>`, but stop after step 3.



.. _migrationguide1.3.5-update-settings:

Update your settings to use django-celery-email
-----------------------------------------------

.. note::

    Settings are configured in ``devilry_prod_settings.py`` (see :ref:`deploy`).

    The default location is ``/etc/devilry``, but it may have been placed in a
    custom location (also explained in :ref:`deploy`).

To configure Devilry to use django-celery-email, do the following:

1. **Make a backup** of your current ``devilry_prod_settings.py``, and put it
   somewhere safe in case the new email backend does not work correctly.
2. Replace the value of your ``EMAIL_BACKEND``-setting with
   ``djcelery_email.backends.CeleryEmailBackend``.
3. Prefix all other ``EMAIL_*``-settings with ``CELERY_``.
4. Add ``djcelery_email`` to the ``INSTALLED_APPS``-setting::

      INSTALLED_APPS += ['djcelery_email']

   Make sure you use ``+=``, NOT ``=``.

You should end up with something like this::

      EMAIL_BACKEND = 'djcelery_email.backends.CeleryEmailBackend'
      CELERY_EMAIL_HOST = 'smtp.example.com'
      CELERY_EMAIL_PORT = 25
      INSTALLED_APPS += ['djcelery_email']

.. warning::

    The fourth step in the list above was not included in the original release
    notes for ``1.3.5``. See
    https://github.com/devilry/devilry-django/issues/480.


Restart supervisord
-------------------
Run the last step of the :ref:`update guide <update>`.


Test that email sending is working
==================================
The that sending email works. You can do this as follows:

1. Logging into the Devilry webUI.
2. Select ``Superuser->Users``.
3. Click yourself (you can search).
4. Click the *Send a test email to <your username>* button.

If you have the correct email address configured in Devilry, you should receive an email if sending is workin.

If **it does not work**, you should restore the old ``devilry_prod_settings.py`` and restart Devilry.