edan_f0/docs/source/releases/v2.0.rst

=======================
Oscar 2.0 release notes
=======================

:release: tbd

Welcome to Oscar 2.0


Table of contents:

.. contents::
    :local:
    :depth: 1


.. _compatibility_of_2.0:

Compatibility
-------------

Oscar 2.0 is compatible with Django 1.11, Django 2.0 and Django 2.1 as well as
Python 3.5 and 3.6.

Support for Python 2.7 and Python 3.4 has been dropped.

.. _new_in_2.0:

What's new in Oscar 2.0?
------------------------

- Added an ``order.OrderStatusChange`` model that is used to log order status changes
  applied by ``Order.set_status()``. This is a new model which will require database migrations to be applied.

- Added an ``OSCAR_OFFERS_INCL_TAX`` setting which can be used to configure whether
  offer discounts are applied on the tax-inclusive amount. This defaults to ``False``,
  to preserve the original behaviour of discount application.

- Added database index definitions for commonly queried fields in a range of models. See `#2875`_.
  This will require projects that have forked Oscar apps to generate corresponding migrations.

.. _`#2875`: https://github.com/django-oscar/django-oscar/pull/2875

Removal of deprecated features
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Support for deprecated product alert email templates was removed The templates
  for these emails have been replaced as follows:

    - ``customer/alerts/emails/confirmation_subject.txt`` is replaced by
      ``customer/emails/commtype_product_alert_confirmation_subject.txt``
    - ``customer/alerts/emails/confirmation_body.txt`` is replaced by
      ``customer/emails/commtype_product_alert_confirmation_body.txt``
    - ``customer/alerts/emails/alert_subject.txt`` is replaced by
      ``customer/emails/commtype_product_alert_subject.txt``
    - ``customer/alerts/emails/alert_body.txt`` is replaced by
      ``customer/emails/commtype_product_alert_body.txt``

  Product alert emails are now sent as Communication Events.

- Support for category URLs without a primary key was removed.

  Enforcement of unique slugs for categories was also removed, as enforcing
  this was inefficient and not threadsafe. Since a primary key is now required
  for category URLs, there is no need for slugs to be unique.

- ``customer.forms.SetPasswordForm`` and ``customer.forms.PasswordChangeForm``
  have been removed. Use ``django.contrib.auth.forms.SetPasswordForm`` and
  ``django.contrib.auth.forms.PasswordChangeForm`` instead.

- The ``views.decorators.staff_member_required`` decorator has been removed. Use
  ``permissions_required(['is_staff']`` instead.

- The ``UserAddress.num_orders`` property has been removed. Use
  ``num_orders_as_shipping_address`` and ``num_orders_as_billing_address``
  instead.

- Backward-compatible dynamic loading of formset classes that have moved in Oscar was
  removed. Projects must update their ``get_class`` calls to use the new paths.

  The paths that have changed are as follows:

  ================================  ==================================  ================
  Old path                          New path                            Affected classes
  ================================  ==================================  ================
  ``basket.forms``                  ``basket.formsets``                 ``BaseBasketLineFormSet``

                                                                        ``BasketLineFormSet``

                                                                        ``BaseSavedLineFormSet``

                                                                        ``SavedLineFormSet``
  ``dashboard.catalogue.forms``     ``dashboard.catalogue.formsets``    ``BaseStockRecordFormSet``

                                                                        ``StockRecordFormSet``

                                                                        ``BaseProductCategoryFormSet``

                                                                        ``ProductCategoryFormSet``

                                                                        ``BaseProductImageFormSet``

                                                                        ``ProductImageFormSet``

                                                                        ``BaseProductRecommendationFormSet``

                                                                        ``ProductRecommendationFormSet``

                                                                        ``ProductAttributesFormSet``

  ``dashboard.promotions.forms``    ``dashboard.promotions.formsets``   ``OrderedProductFormSet``
  ``wishlists.forms``               ``wishlists.formsets``              ``LineFormset``
  ================================  ==================================  ================

- Added the ability to manage ``catalogue.Option`` objects from the dashboard.

Minor changes
~~~~~~~~~~~~~
- Dropped ``action=""`` and ``action="."`` attributes, following the lead of Django
  and as per the HTML5 specification.

- Replaced use of Django's procedural auth views with the corresponding
  class-based views.

- ``OrderPlacementMixin.get_message_context()`` is now passed a ``code`` argument
  specifying the communication event type code for a message being sent.

- We've dropped the dependency on Unidecode due to license incompatibilities,
  ``oscar.core.utils.default_slugifier`` now uses ``oscar.core.utils.cautious_slugify``
  to handle unicode characters in slugs when ``OSCAR_SLUG_ALLOW_UNICODE`` is ``False``.

- ``OSCAR_SLUG_FUNCTION`` previously accepted a function as its value. It now
  only accepts a dotted path to a function as its value. Such functions must
  also now take a ``allow_unicode`` kwarg.

- Fixed input validation for ``dashboard.offers.forms.BenefitForm`` when a ``range``
  was specified but other fields were empty.

- Fixed calculation of weight-based shipping charges in cases where the basket
  weight is an exact multiple of a weight band's upper limit.

- The ``sort_by`` field on ``catalogue.reviews.SortReviewsForm`` was made optional
  and the logic in ``ProductReviewList`` adjusted so that the form fields
  don't have to be rendered manually because of form errors.

- Added a ``datetime_filters`` tag library that provides a ``timedelta`` template
  filter for rendering time deltas in human readable format.

- ``OSCAR_OFFER_ROUNDING_FUNCTION`` previously accepted a function as its value. It now
  only accepts a dotted path to a function as its value

- Fixed the logic of ``offers.Range.all_products()`` to make it consistent with
  ``Range.contains_product()`` in excluding products specified in ``excluded_product_ids``.

- Added a ``COMPARISON_FIELDS`` constant to ``catalogue.Category`` to restrict
  which fields are fetched from the database when performing category comparison queries.

- Significantly improved the database efficiency of the ``category_tree`` template tag.

- Order confirmation emails now include an order status link for authenticated users, as well as guest users, and order status is displayed consistently in both logged-in and anonymous order detail views.

- Fixed display of styled HTML emails in account email detail views, wrapping them in an iframe to avoid leakage of styles into the page.

.. _incompatible_in_2.0:

Backwards incompatible changes in Oscar 2.0
-------------------------------------------

- Redirection to the parent detail view for child products is disabled by default.
  Child products now have their own detail view, which allows displaying their price
  and images independently from the parent product. To revert to the previous behaviour
  of redirecting to the parent product, set
  ``oscar.apps.catalogue.views.ProductDetailView.enforce_parent`` to ``False``.

- Renamed the modules containing the Django app config classes for Oscar apps
  (apart from the ``oscar`` app), from ``config`` to ``apps``.

- Removed the ``app`` modules of Oscar apps, moving the configs (related to
  permissions, URLconfs, and feature hiding) they contained into the apps'
  Django app config classes. They include the following attributes: ``name``
  (since renamed ``namespace``), ``login_url``, ``hidable_feature_name``,
  ``permissions_map``, and ``default_permissions``; methods:
  :meth:``get_urls``, :meth:``post_process_urls``, :meth:``get_permissions``,
  :meth:``get_url_decorator``, and :meth:``urls``; and their respective view
  classes. The composite config classes for normal Oscar apps are subclasses of
  ``oscar.core.application.OscarConfig`` (previously
  ``oscar.core.application.Application``), and for Oscar Dashboard apps
  ``oscar.core.application.OscarDashboardConfig`` (previously
  ``oscar.core.application.DashboardApplication``).

- Removed the ``application`` variable, which previously held an Oscar app
  config instance, from the Oscar app config module. A single Django/Oscar app
  config instance is now registered in the Django app registry, for each app
  label. It should be obtained by looking it up in the Django app registry.

- Changed the values returned by the Oscar app config ``urls`` property. It now
  returns a tuple containing the list of URL patterns, the app namespace (which
  could previously be None, but not any more), and the instance namespace
  (which would previously be overiden by the app namespace, if left blank, but
  must now be explicitly set). To include URLs with an instance namespace, use
  the form ``app_config.urls``, and to include URLs without an instance
  namespace, use the form ``django.conf.urls.include(app_config.urls[0])``.

- Removed :meth:``oscar.get_core_apps``. Overridding apps is now done by
  replacing the Oscar app entry in the ``INSTALLED_APPS`` setting with that of
  the forked app.

- Changed the calling signature for the ``oscar_fork_app`` management command.
  The ``app_label`` argument is the Django app label of the app to be forked.
  ``target_path`` is the directory into which the new app shall be copied.
  ``new_app_subpackage`` is the optional dotted path to the subpackage of the
  new app, from which, together with the ``target_path``, the full Python path
  to the app will be derived. If a ``new_app_subpackage`` is omitted, then the
  subpackage of the app being forked will be used instead.

Migrating forked apps
~~~~~~~~~~~~~~~~~~~~~

- For each forked app:
  - Rename the module that contains the Django app config class, from
    ``config.py`` to ``apps.py``.
  - Change the ``default_app_config`` variable in the ``__.init__.py`` module to
    point to the new Django app config class.
  - Change the Django app config class's inheritance base class to the one in
    the parent app's ``apps`` module (it should be a
    ``oscar.core.application.OscarConfig`` or
    ``oscar.core.application.OscarDashboardConfig`` subclass).
  - Move the Oscar app configs from the ``oscar.core.application.Application``
    or ``oscar.core.application.DashboardApplication`` subclass in its
    ``app.py`` module, to the corresponding
    ``oscar.core.application.OscarConfig`` or
    ``oscar.core.application.OscarDashboardConfig`` subclass in the ``apps.py``
    module.
    - These include the following overridden attributes:
      - Rename ``name`` to ``namespace``
      - ``login_url``
      - ``hidable_feature_name``
      - ``permissions_map``
      - ``default_permissions``
    - These include the following overridden methods:
      - :meth:``get_urls``
      - :meth:``post_process_urls``
      - :meth:``get_permissions``
      - :meth:``get_url_decorator``
      - :meth:``urls``
  - For URLconfs that include Oscar app URLs (e.g. in the ``dashboard`` app):
    - Obtain the app's Django/Oscar app config instance from the Django app
      registry, instead of from the app's previous config module's (``app.py``)
      ``application`` variable.
    - If the to-be-included URLs have an instance namespace, use the form
      ``app_config.urls``, which passes in the list of URL patterns, the app
      namespace, and the instance namespace.
    - If the to-be-included URLs do not have an instance namespace, use the
      form ``include(app_config.urls[0])``, which only passes in the list of
      URL patterns.

- For the main app's URLconf:
  - Obtain the ``oscar`` app's Django/Oscar app config instance from the Django
    app registry, instead of from the previous config module's (``config.py``)
    ``application`` variable.
  - Include the ``oscar`` app's URLs using the form
    ``include(app_config.urls[0])``, to only pass in the list of URL patterns,
    and not an app or instance namespace.

Dependency changes
------------------

- Upgraded TinyMCE to version 4.8.3.

- Upgraded jQuery inputmask to version 4.0.2.

.. _deprecated_features_in_2.0:

Deprecated features
~~~~~~~~~~~~~~~~~~~

- ``offer.Range.contains()`` is deprecated. Use ``contains_product()`` instead.

- ``catalogue.managers.ProductManager`` is deprecated.
  Use ``catalogue.managers.ProductQuerySet.as_manager()`` instead.

- ``catalogue.managers.BrowsableProductManager`` is deprecated.
  Use ``Product.objects.browsable()`` instead.