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

========================================
Oscar 3.0 release notes (in development)
========================================

:release: TBD

Welcome to Oscar 3.0!

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

.. _compatibility_of_3.0:

Compatibility
~~~~~~~~~~~~~


.. _new_in_3.0:

What's new in Oscar 3.0?
~~~~~~~~~~~~~~~~~~~~~~~~

- Oscar 3.0 features a major upgrade of Oscar's default templates and styles to use Bootstrap version 4.
  Both the front-end and dashboard templates have been refactored to work with Bootstrap 4. This is a major,
  non-backward compatible change for projects that rely on or extend the default Oscar templates.

- As with Bootstrap 4 itself, Oscar's default styles are now defined using SASS instead of LESS.

- To replace Bootstrap 3's Glyphicons, Oscar's default templates now rely on Font Awesome.

- Support has been added to the ``catalogue.Option`` model to define the
  type of option. This is used by the ``AddToBasketForm`` to determine the appropriate form field to display for that
  option in the add-to-cart form. Currently supported types are: text, integer, float, boolean, and date.

  The ``type`` field on the ``Option`` model (previously used to denote whether the option is required)
  has been repurposed to store the type of the option, and a new ``required`` field
  has been added to denote whether the option is required. Projects that have forked the catalogue app will
  need to generate custom migrations for these model field changes.
  Projects should pay close attention to the data migration provided in
  ``catalogue/migrations/0019_option_required.py`` for this change.

- Added support for restricted combinations of offers. When creating an offer in the dashboard,
  administrators can now define a restricted set of other offers that offer can be used in combination with.
  This changes introduces a new ``combinations`` field on the ``Offer`` model which requires a database migration.

- Report generator classes now can define ``model_class`` or ``queryset``, similar to Django class based views.
  You can also override queryset in the ``get_queryset`` method. Filtering by date range is now properly applied
  during CSV export as well.

- New fields ``meta_title`` and ``meta_description`` have been added to both the ``Product`` and ``Category`` models,
  which can be used to override the HTML title and meta description content for product and category pages. These
  are editable from the search engine optimisation tab in the dashboard edit views for products and categories
  respectively. A database migration is required for this change.

Backwards incompatible changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- The ``StockRecord.price_excl_tax`` field has been renamed to ``StockRecord.price``.
  Projects that have forked the ``partner`` app will need to generate their own migration
  to rename this field.

- The ``annotate_form_field`` template tag will now set the ``widget_type`` in `the format of Django 3.1`_: so no longer
  ``CheckboxField``, but just ``checkbox``.

.. _`the format of Django 3.1`: https://docs.djangoproject.com/en/3.1/ref/forms/api/#django.forms.BoundField.widget_type

Bug fixes
~~~~~~~~~

- ``catalogue.product_attributes.ProductAttributesContainer`` was refactored to ensure that attributes
  inside the container are always properly loaded at initialisation. The container is now wrapped in a
  ``SimpleLazyObject`` when assigned to ``Product.attr``. ``ProductAttributesContainer.initiate_attributes()``
  was removed as the database query now happens on instantiation.

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

- Several deprecated model fields have been removed in Oscar 3.0:

   - ``order.Line.est_dispatch_date``
   - ``order.Line.unit_cost_price``
   - ``order.Line.unit_retail_price``
   - ``partner.StockRecord.cost_price``
   - ``partner.StockRecord.price_retail``

  Oscar ships with migrations that remove these fields. If you want to continue using them,
  please make sure you add the fields back to your forked app before migrating. Projects
  that have forked the ``order`` and ``partner`` apps will need to generate their own
  migrations to remove these fields.


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

- Several models were updated to define a default ordering, to avoid issues with inconsistent ordering of
  items in the dashboard and elsewhere. Database migrations are required for these changes.

- Category slugs can now be edited via the dashboard.

- A new method ``get_attribute_values()`` was added to the Product model which returns a merged set of
  attribute values for child and parent products.

- The behaviour of ``checkout.views.ThankYouView`` when no order is found in the session has changed,
  to redirect the user to the URL defined by ``settings.OSCAR_HOMEPAGE`` instead of returning a page not found error.

Dependency changes
~~~~~~~~~~~~~~~~~~

Python package dependencies:


Javascript dependencies:


.. _deprecated_features_in_2.0:

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