Update 0.8 release notes re shipping method changes

docs/source/howto/how_to_configure_shipping.rst

@@ -109,10 +109,10 @@ The repository class is responsible for return shipping method instances.  Oscar
 defines several of these but it is easy to write your own, their interface is
 simple.
 
-The base shipping method class ``oscar.apps.shipping.base.Base`` (that
+The base shipping method class ``oscar.apps.shipping.methods.Base`` (that
 all shipping methods should subclass has API:
 
-.. autoclass:: oscar.apps.shipping.base.Base
+.. autoclass:: oscar.apps.shipping.methods.Base
     :members:
     :noindex:
 

docs/source/ref/apps/shipping.rst

@@ -85,9 +85,6 @@ Simple really - follow these steps:
 Methods
 -------
 
-.. automodule:: oscar.apps.shipping.base
-    :members:
-
 .. automodule:: oscar.apps.shipping.methods
     :members:
 

docs/source/ref/templatetags.rst

@@ -0,0 +1,74 @@
+=============
+Template tags
+=============
+
+Shipping tags
+-------------
+
+Load these tags using ``{% load shipping_tags %}``.
+
+``shipping_charge``
+~~~~~~~~~~~~~~~~~~~
+
+Injects the shipping charge into the template context:
+
+Usage:
+
+.. code-block:: html+django
+
+   {% shipping_charge shipping_method basket as name %}
+   Shipping charge is {{ name }}.
+
+The arguments are:
+
+===================  =====================================================
+Argument             Description
+===================  =====================================================
+``shipping_method``  The shipping method instance
+``basket``           The basket instance to calculate shipping charges for
+``name``             The variable name to assign the charge to
+===================  =====================================================
+
+``shipping_charge_discount``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Injects the shipping discount into the template context:
+
+Usage:
+
+.. code-block:: html+django
+
+   {% shipping_discount shipping_method basket as name %}
+   Shipping discount is {{ charge }}.
+
+The arguments are:
+
+===================  =====================================================
+Argument             Description
+===================  =====================================================
+``shipping_method``  The shipping method instance
+``basket``           The basket instance to calculate shipping charges for
+``name``             The variable name to assign the charge to
+===================  =====================================================
+
+``shipping_charge_excl_discount``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Injects the shipping charges with no discounts applied into the template context:
+
+Usage:
+
+.. code-block:: html+django
+
+   {% shipping_charge_excl_discount shipping_method basket as name %}
+   Shipping discount is {{ name }}.
+
+The arguments are:
+
+===================  =====================================================
+Argument             Description
+===================  =====================================================
+``shipping_method``  The shipping method instance
+``basket``           The basket instance to calculate shipping charges for
+``name``             The variable name to assign the charge to
+===================  =====================================================

docs/source/releases/v0.8.rst

@@ -17,6 +17,8 @@ Overview
 
 Oscar now has a demo site customised for the US!
 
+Shipping methods got a thorough re-working.
+
 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.
@@ -50,30 +52,17 @@ Customisation just got easier!
 * The documentation around :doc:`/topics/customisation` has been given an
   overhaul to incorporate the changes.
 
-US demo site
-------------
+Reworked shipping app
+---------------------
 
-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.
+Several parts of the shipping app have been changed. The most important is a
+change to the API of shipping methods to avoid a potential thread safety issue.
 
-See :ref:`us_site` for more information.
-
-Cleanup around shipping methods
--------------------------------
+Other changes to the shipping app include:
 
-* The models of the shipping app now have abstract base classes, similar to
+* All shipping models 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.
 
@@ -81,6 +70,22 @@ Cleanup around shipping methods
   made slightly more useful. Contributions for a dedicated dashboard app are
   most welcome!
 
+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.
+
+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.
+
 .. _minor_changes_in_0.8:
 
 Minor changes
@@ -117,6 +122,68 @@ Bugfixes
 Backwards incompatible changes in 0.8
 =====================================
 
+.. _incompatible_shipping_changes_in_0.8:
+
+Shipping app
+------------
+
+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 to the method. This was really a
+crutch to allow templates to have easy access to shipping charges. 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 template tags 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:
+
+* The :class:`~oscar.apps.order.utils.OrderCreator` class now requires the
+  ``shipping_charge`` to be passed to ``place_order``.
+
+* The :class:`~oscar.apps.order.utils.OrderCreator` class no longer defaults to
+  free shipping: a shipping method and charge has to be explicitly passed in.
+
+* The signature of the :class:`~oscar.apps.checkout.calculators.OrderTotalCalculator` 
+  class has changed to accept the 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.
+
+Other potentially breaking changes to the shipping app:
+
+* Shipping methods no longer have ``charge_excl_tax``,
+  ``charge_incl_tax`` and ``is_tax_known`` properties.
+
+* 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 ``shipping`` app saw a few renames; please see the section above.
 * The ``oscar_calculate_scores`` command has been `rewritten`_ to use the ORM
   instead of raw SQL. That exposed a bug in the previous calculations,