edan_f0/docs/source/releases/v0.8.rst

=======================
Oscar 0.8 release notes
=======================

.. warning::

   Since v0.8 has not been released yet, these release notes are still a work-in-progress.

Welcome to Oscar 0.8!

Table of contents:

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

.. _overview_of_0.8:

Overview
--------

Oscar now has a demo site customised for the US!

Things that have been heavily rewritten:

- Adding product to the basket

Shipping functionality got a thorough re-working including a new dashboard for
weight-based shipping methods.

Lots of methods deprecated in the 0.6 release have now been removed.
Specifically, the partner "wrapper" functionality is now gone. All price and
availability logic now needs to be handled with strategies.

.. _compatibility_of_0.8:

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

Oscar 0.8 is compatible with Django 1.5-1.7. 

Support for Python 2.6 has been dropped; Oscar works with Python 2.7, 3.3
and 3.4.

.. _new_in_0.8:

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

Customisation just got easier!
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Oscar's views are now dynamically imported. This means that they can be
  overridden like most other classes in Oscar; overriding the related
  Application instance is not necessary any more.

* A new management command, ``oscar_fork_app``, has been introduced to help
  with the all-to-common pattern of forking an Oscar app to override one of
  it's classes.

* The documentation around :doc:`/topics/customisation` has been given an
  overhaul to incorporate the changes.

Reworked shipping app
~~~~~~~~~~~~~~~~~~~~~

Several parts of the shipping app have been altered The most important change is a
to the API of shipping methods to avoid a potential thread safety issue.
Any existing Oscar sites with custom shipping methods will need to adjust them
to confirm to the new API.

Other changes to the shipping app include:

* All shipping models now have abstract base classes, similar to
  the rest of Oscar, allowing them to be customised in the standard way.

* The ``WeightBand.upper_limit`` model field is now a ``DecimalField``, just like the other
  weight-related fields.

* The Django admin interface for the ``WeightBased`` shipping method has been
  made slightly more useful. 

See the 
:ref:`backwards incompatible changes <incompatible_shipping_changes_in_0.8>` 
for the shipping app and the 
:doc:`guide to configuring shipping </howto/how_to_configure_shipping>` 
for more information.

Dashboard for weight-based shipping methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There is a new dashboard for weight-based shipping methods. It isn't enabled by
default as weight-based shipping methods are enabled by default. To add it to
the dashboard menu, include this snippet in your ``OSCAR_DASHBOARD_NAVIGATION``
setting:

.. code-block:: python

    OSCAR_DASHBOARD_NAVIGATION = [
        ...
        {
            'label': _('Shipping charges'),
            'url_name': 'dashboard:shipping-method-list',
        },
        ...
    ]

You'll also need to modify your shipping repository class to return weight-based
shipping methods too.

US demo site
~~~~~~~~~~~~

To help developers building sites for the US, a new example Oscar site has been
included in the repo. This customises core Oscar to treat all prices as
excluding tax and then calculate and apply taxes once the shipping address is
known.

See :ref:`us_site` for more information.

Basket additions clean-up
~~~~~~~~~~~~~~~~~~~~~~~~~

The forms and views around adding things to your basket has been vigorously
reworked. This cleans up some very old code there and ensures variant products
are handled in a consistent way.

The changes do require changing the constructor signature of the
``AddToBasketForm`` - the details are documented in the
:ref:`basket_app_changes`.

Checkout improvements
~~~~~~~~~~~~~~~~~~~~~

The checkout process now skips payment if the order total is zero (e.g. when
ordering free products or using a voucher). As part of that, checkout views
now evaluate *pre-conditions* (as before) and newly introduced
*skip conditions*. This should make customising the checkout flow easier.

Cleanup around shipping methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* The models of the shipping app now have abstract base classes, similar to
  the rest of Oscar.

* The legacy ``ShippingMethod`` name of the interface of the shipping app has
  been removed. Inherit from ``shipping.base.Base`` for the class instead, and
  inherit from ``shipping.abstract_models.AbstractBase`` for model-based
  shipping methods.

* ``oscar.apps.shipping.Scales`` has been renamed and moved to
  ``oscar.apps.shipping.scales.Scale``, and is now overridable.

* ``WeightBand.upper_limit`` is now a ``DecimalField``, just like the other
  weight-related fields.

* The Django admin interface for the ``WeightBased`` shipping method has been
  made slightly more useful. Contributions for a dedicated dashboard app are
  most welcome!

.. _minor_changes_in_0.8:

Minor changes
~~~~~~~~~~~~~

* The ``OSCAR_CURRENCY_LOCALE`` setting has been removed. The locale is now
  automatically determined from the current language. This ensures prices are
  always shown in the correct format when switching languages.

* The login and registration view now redirects staff users to the dashboard
  after logging in. It also employs flash messages to welcome returning and
  newly registered users.

* The basket middleware now assigns a ``basket_hash`` attribute to the
  ``request`` instance. This provides a hook for basket caching.

* The tracking pixel now also reports the Oscar version in use. This was
  forgotten when adding tracking of the Python and Django version in 0.7.
  Total information collected now is the versions of Django, Python and Oscar.

* ``OSCAR_SLUG_FUNCTION`` now accepts both string notation and a callable.

* The default templates now allow the order status to be changed on the
  dashboard order detail page.

* The forms for the order dashboard views are now loaded dynamically so they
  can be overridden.

.. _incompatible_changes_in_0.8:

Backwards incompatible changes in 0.8
-------------------------------------

.. _incompatible_shipping_changes_in_0.8:

Shipping
~~~~~~~~

The shipping method API has been altered to avoid potential thread-safety
issues. Prior to v0.8, shipping methods had a ``set_basket`` method which
allowed a basket instance to be assigned. This was really a crutch to allow
templates to have easy access to shipping charges (as they could be read
straight off the shipping method instance). However, it was also a
design problem as shipping methods could be instantiated at compile-time
leading to a thread safety issue where multiple threads could assign a basket
to the same shipping method instance.

In Oscar 0.8, shipping methods are stateless services that have a method
:func:`~oscar.apps.shipping.methods.Base.calculate` that takes a basket and
returns a ``Price`` instance.  New :doc:`template tags </ref/templatetags/>` are
provided that allow these shipping charges to be accessed from templates.

This API change does require quite a few changes as both the shipping method
and shipping charge now need to be passed around separately:

* Shipping methods no longer have ``charge_excl_tax``,
  ``charge_incl_tax`` and ``is_tax_known`` properties.

* The :class:`~oscar.apps.order.utils.OrderCreator` class now requires the
  ``shipping_charge`` to be passed to ``place_order``.

* The signature of the :class:`~oscar.apps.checkout.calculators.OrderTotalCalculator` 
  class has changed to accept ``shipping_charge`` rather than a
  ``shipping_method`` instance.

* The signature of the
  :func:`~oscar.apps.checkout.session.CheckoutSessionMixin.get_order_totals` 
  method has changed to accept the ``shipping_charge`` rather than a
  ``shipping_method`` instance.

Another key change is in the shipping repository object. The
``get_shipping_methods`` method has been split in two to simplify the exercise
of providing new shipping methods. The best practice for Oscar 0.8 is to 
override the ``methods`` attribute if the same set of shipping methods is
available to everyone:

.. code-block:: python

    from oscar.apps.shipping import repository, methods

    class Standard(methods.FixedPrice):
        code = "standard"
        name = "Standard"
        charge_excl_tax = D('10.00')


    class Express(methods.FixedPrice):
        code = "express"
        name = "Express"
        charge_excl_tax = D('20.00')

    class Repository(repository.Repository):
        methods = [Standard(), Express()]
        
or to override ``get_available_shipping_methods`` if the available shipping
methods if only available conditionally:

.. code-block:: python

    from oscar.apps.shipping import repository

    class Repository(repository.Repository):
        
        def get_available_shipping_methods(
                self, basket, shipping_addr=None, **kwargs):
            methods = [Standard()]
            if shipping_addr.country.code == 'US':
                # Express only available in the US
                methods.append(Express())
            return methods

Note that shipping address should be passed around as instances not classes.

Other potentially breaking changes related to shipping include:

* The :class:`~oscar.apps.order.utils.OrderCreator` class no longer defaults to
  free shipping: a shipping method and charge have to be explicitly passed in.

* The ``Base`` shipping method class now lives in ``oscar.apps.shipping.methods``.

* The ``find_by_code`` method of the shipping ``Repository`` class has been
  removed as it is no longer used. 

* The parameters for
  :func:`oscar.apps.shipping.respository.Repository.get_shipping_methods`
  have been re-ordered to reflect which are the most important.

* The legacy ``ShippingMethod`` name of the interface of the shipping app has
  been removed. Inherit from ``shipping.base.Base`` for the class instead, and
  inherit from ``shipping.abstract_models.AbstractBase`` for model-based
  shipping methods.

* ``oscar.apps.shipping.Scales`` has been renamed and moved to
  ``oscar.apps.shipping.scales.Scale``, and is now overridable.

Misc
~~~~

* The ``oscar_calculate_scores`` command has been `rewritten`_ to use the ORM
  instead of raw SQL. That exposed a bug in the previous calculations,
  where purchases got weighed less than any other event. When you upgrade,
  your total scores will be change. If you rely on the old behaviour,
  just extend the ``Calculator`` class and adjust the weights.

* ``Product.score`` was just duplicating ``ProductRecord.score`` and has been
  removed. Use ``Product.stats.score`` instead.

* Oscar has child products to model tightly coupled products, and
  ``Product.recommended_products`` to model products that are loosely related
  (e.g. used for upselling). ``Product.related_products`` was a
  third option that sat somewhere in between, and which was not well supported.
  We fear it adds confusion, and in the spirit of keeping Oscar core lean,
  has been removed. If you're using it, switch to
  ``Product.recommended_products`` or just add the field back to your
  custom Product instance and ``ProductForm`` when migrating.

.. _rewritten: https://github.com/tangentlabs/django-oscar/commit/d8b4dbfed17be90846ea4bc47b5f7b39ad944c24

Basket line stockrecords
~~~~~~~~~~~~~~~~~~~~~~~~

The basket line model got a reference to the stockrecord in Oscar 0.6. The
basket middleware since then updated basket lines to have stockrecords if
one was missing. If any lines are still missing a stockrecord, we'd expect them
to be from from submitted baskets or from old, abandoned baskets.
This updating of basket lines has been removed for 0.8 as it incurs additional
database queries. Oscar 0.8 now also enforces the stockrecord by making it
the ``stockrecord`` field of basket ``Line`` model no longer nullable.

There is a migration that makes the appropriate schema change but, before that
runs, you may need to clean up your ``basket_line`` table to ensure that all
existing null values are replaced or removed.

Here's a simple script you could run before upgrading which should ensure there
are no nulls in your ``basket_line`` table:

.. code-block:: python

    from oscar.apps.basket import models
    from oscar.apps.partner.strategy import Selector

    strategy = Selector().strategy()

    lines = models.Line.objects.filter(stockrecord__isnull=True):
    for line in lines:
        info = strategy.fetch_for_product(line.product)
        if line.stockrecord:
            line.stockrecord = info.stockrecord
            line.save()
        else:
            line.delete()

* The ``reload_page_response`` method of 
  :class:`~oscar.apps.dashboard.orders.views.OrderDetailView`
  has been renamed to ``reload_page``.

.. _basket_app_changes:

Basket app changes
~~~~~~~~~~~~~~~~~~

- The ``basket:add`` URL now required the primary key of the "base" product to
  be included. This allows the same form to be used for both GET and POST
  requests for variant products.

- The ``ProductSelectionForm`` is no longer used and has been removed.

- The constructor of the :class:`~oscar.apps.basket.forms.AddToBasketForm` has
  been adjusted to take the basket and the purchase info tuple as parameters
  instead of the request instance (c74f57bf_ and 8ba283e8_).

.. _c74f57bf: https://github.com/tangentlabs/django-oscar/commit/c74f57bf434661877f4d2d2259e7e7eb18b34951#diff-d200ac8746274e0307f512af886e1f3eR148
.. _8ba283e8: https://github.com/tangentlabs/django-oscar/commit/8ba283e8c4239e4eff95da5e8097a17ecfadf5f5

Migrations
~~~~~~~~~~

* Catalogue:

    - ``0021`` - Add ``unique_together`` to ``ProductAttributeValue``,
      ``ProductRecommendation`` and ``ProductCategory``
    - ``0022`` - Remove ``Product.score`` field.

* Order:

    - ``0029`` - Add ``unique_together`` to ``PaymentEventQuantity`` and ``ShippingEventQuantity``

* Promotions:

    - ``0006`` - Add ``unique_together`` to ``OrderedProduct``

* Shipping:

    - ``0007`` - Change ``WeightBand.upper_limit`` from ``FloatField`` to ``DecimalField``
    - ``0008`` - Drop ``WeightBased.upper_charge`` field.

.. _deprecated_features_in_0.8:

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

These methods have been removed:

* ``oscar.apps.catalogue.abstract_models.AbstractProduct.has_stockrecord``
* ``oscar.apps.catalogue.abstract_models.AbstractProduct.stockrecord``
* ``oscar.apps.catalogue.abstract_models.AbstractProduct.is_available_to_buy``
* ``oscar.apps.catalogue.abstract_models.AbstractProduct.is_purchase_permitted``
* ``oscar.apps.catalogue.views.get_product_base_queryset``
* ``oscar.apps.partner.abstract_models.AbstractStockRecord.is_available_to_buy``
* ``oscar.apps.partner.abstract_models.AbstractStockRecord.is_purchase_permitted``
* ``oscar.apps.partner.abstract_models.AbstractStockRecord.availability_code``
* ``oscar.apps.partner.abstract_models.AbstractStockRecord.availability``
* ``oscar.apps.partner.abstract_models.AbstractStockRecord.max_purchase_quantity``
* ``oscar.apps.partner.abstract_models.AbstractStockRecord.dispatch_date``
* ``oscar.apps.partner.abstract_models.AbstractStockRecord.lead_time``
* ``oscar.apps.partner.abstract_models.AbstractStockRecord.price_incl_tax``
* ``oscar.apps.partner.abstract_models.AbstractStockRecord.price_tax``

These classes have been removed

* ``oscar.apps.partner.prices.DelegateToStockRecord``
* ``oscar.apps.partner.availability.DelegateToStockRecord``