These release notes cover the new features as well as backwards incompatible changes
that you’ll want to be aware of when upgrading from Oscar 0.5 or
earlier. This release contains some major changes to core APIs which means
many old APIs are scheduled to be dropped - see the deprecation plan to avoid any
nasty surprises.

The biggest change in Oscar 0.6 is the reworking of pricing and availability, which
builds on top of the change to allow multiple stockrecords per product. The
change is largely backwards compatible with the old system of “partner
wrappers” but it is recommended to upgrade to the new system. Support for
partner wrappers will be removed for Oscar 0.7.

Oscar 0.6 also introduces better support for marketplace-like functionality
with the so-called permission-based dashboard. It is now possible to give
non-staff users access to a subset of the dashboard’s views (products and
orders) by setting the new dashboard_access permission.

Oscar now supports Django 1.5 and its custom user model. This has been only
tested in the context of starting a new Oscar project with a custom model.
Switching from a separate “profile” model to the new system is not recommended
at this point.

Oscar also supports Django 1.6 although this is considered experimental at this
stage. It’s possible there are still some incompatibilities that haven’t been
teased out just yet.

Products can now have multiple stockrecords rather than just one. This is a
key structural change that paves the way for many advanced features.

If a product can be fulfilled by multiple partners, a different stockrecord can
be created for each partner. This is a common requirement for large-scale
e-commerce sites selling millions of products that use many different
fulfillment partners.

It also allows better support for international sites as stockrecords can be
created for partners in different countries, who sell in different currencies.

When products can have many stockrecords, a process needs to be in place to
choose which one is selected for a given customer and product. To handle this,
a new “strategy” class has been introduced, responsible for selecting the appropriate
stockrecord for a given customer and product.

This change also paved the way for reworking how prices, taxes and availability
are handled. Instead of using “partner wrappers”, the strategy class is
responsible for returning availability details and prices for a particular
product. New classes known as pricing and availability policies are used to
cleanly encapsulate this information.

These changes allow Oscar to dynamically determine prices, partner and availability
for a given customer and product. This enables several advanced features such as:

Fulfilling a product from the partner that offers the best margin.

Fulfilling a product from the partner geographically closest to the customer.

Automatically switching to a new partner when when stock runs out.

Supporting transactions in multiple currencies on the same site.

Supporting different tax treatments on the same site (eg UK VAT and US sales
tax)

Having different pricing and availability policies for different customers.

More generally, it provides a structure for customising how pricing,
availability work on a per-customer basis. This gives a great deal of
flexibility.

Three changes were necessary to better support marketplace scenarios within
Oscar:

Oscar’s core Application class now supports
specifying permissions on a per-view basis. This is done via a new default
decorator. Legacy behaviour is unchanged.

The dashboard’s menus are now built dynamically. If the current user does
not have access to some views in OSCAR_DASHBOARD_NAVIGATION, they will
be omitted in the menu returned by
oscar.apps.dashboard.nav.create_menu().

The index, catalogue and order dashboard views have been modified to allow
access to non-staff users. See the dashboard documentation for details.

Wishlist functionality has finally landed. Signed in customers are now able to
create multiple named wishlists and add products to them. There is a new
section in the customer’s account where wishlists can be managed.

The PaymentDetailsView checkout view has
been restructured for flexibility. There is a new
build_submission() method
which is responsible for building a dict of all data for passing to the
submit method. This includes the shipping address and shipping method
which were previously loaded indirectly within the submit method.

Oscar now ships with a demo site along side the sandbox site. While the sandbox
is a minimal Django project that uses Oscar with all its defaults, the demo site
is a more realistic example of an Oscar project. It has a custom skin and makes
many alterations to the default Oscar behaviour.

Specifically, Oscar supports custom user models, the headline new feature in Django
1.5. These can be used standalone or with a one-to-one profile model: Oscar’s
account forms inspect the model fields to dynamically pick up the fields for
editing and display.

There are some restrictions on what fields a custom user model must have. For
instance, Oscar’s default auth backend requires the user model to have an email
and password field. New Oscar projects are encouraged to use the provided
abstract user model as the base for their users.

Support for Django 1.6 is considered experimental at the moment as there hasn’t
been time to run thorough tests for all possible incompatibilities.

The views and templates of the accounts section have been reworked to be clearer
and easier to extend. There is no longer a generic frontpage for the accounts
section - instead, each subsection has its own page. The navigation has also
moved to the left-hand side.

Oscar’s search app has been reviewed and simplified. The main view class
(now FacetedSearchView)
has been reworked to provide better support for faceting, which can be easily
specified using the OSCAR_SEARCH_FACETS setting.

The SuggestionsView has been removed as it wasn’t being used. A later
version of Oscar will include a replacement.

Oscar’s dashboard now serves a single pixel image from one of Tangent’s
servers. This is included to gather information on which sites use Oscar,
which is an important metric for Tangent, who sponsor Oscar’s development.

It can easily be disabled by setting OSCAR_TRACKING=False. If you do opt
out, please email the mailing list with any production Oscar sites you are
running. This will help to ensure investment in Oscar’s future.

detox is a new dependency, which allows running tox tests in parallel.

OSCAR_ALLOW_ANON_REVIEWS has been a documented setting since Oscar 0.4.
But there’s never been any code to support this, which has been rectified with
this release. Things should now work as expected.

Oscar uses a cookie to display recently displayed products. This cookie never
expired and wasn’t a HttpOnly cookie. It is now a HttpOnly cookie and expires
after 7 days. Additionally, two settings have been introduced to configure
it analogues to the basket cookies:
OSCAR_RECENTLY_VIEWED_COOKIE_LIFETIME and
OSCAR_RECENTLY_VIEWED_COOKIE_NAME.

If you are using the get_core_apps helper function, then these new apps
will be added automatically. The new wishlists app contains database migrations,
so you will need to run the migrate management command.

Several changes have been made to the checkout in the name of simplification
and making things easier to customise.

The PaymentDetailsView has been adjusted to explicitly pass variables
around rather than relying on methods that load them on demand. This makes
customisation easier and everything more explicit (a good thing).

The submit method in
PaymentDetailsView has a new signature.
It now accepts the user, shipping address, shipping method and order total as
required parameters The intention is that the build_submission methods
returns a dict of kwargs for submit so that it can be called like:

submission=self.build_submission()returnself.submit(**submission)

If your payment or order submission process requires additional parameters (eg
a bankcard instance), override the build_submission method to provide them. The
dict returned from the new build_submission method is also passed to the
template.

The handle_payment method in
PaymentDetailsView now accepts a
Price instance instead of a Decimal for the order
total.

The handle_order_placement method in
OrderPlacementMixin
now accepts the user, shipping address and shipping method in a
different order consistent with the submit method from
PaymentDetailsView.

The place_order method in
OrderPlacementMixin
has a new signature. The parameters have been reordered and the shipping
address, shipping method and billing address must be passed in explicitly (as
unsaved instances).

The create_shipping_address method in
OrderPlacementMixin has changed
signature. Instead of being passed a basket, it is now passed the user and
an unsaved shipping address instance.

The create_billing_address method in
OrderPlacementMixin has changed
signature. It is now passed an unsaved billing address instance as well as
a shipping address instance.

The get_shipping_method (from
CheckoutSessionMixin) no longer
defaults to returning free shipping if no shipping method can be looked up.

The OrderTotalCalculator now
returns a Price instance from a new calculate
method. The old methods order_total_incl_tax and
order_total_excl_tax have been removed.

Other changes:

The checkout gateway page has a new option “Register and continue” which allows a customer
to register before checking out. As part of this change, the option value new in
GatewayForm has changed to guest as new option is used for this feature.

The checkout decorators basket_required and prev_steps_must_be_complete have been removed as they were
no longer used.

The default implementation of the
Repository class
has been adjusted to avoid thread-safety issues. If you define your own
shipping Repository class, ensure that your shipping methods are
instantiated per-request and not at compile time.

fromoscar.apps.shippingimportrepositoryclassRepository(repository.Repository)# Note, methods are not instantiated. The get_shipping_methods# method will instantiate them.methods=[SomeMethod,AnotherMethod]

Warning

Beware of shipping methods that are configured via constructor parameters, like
FixedPrice. If you are using methods
that work this way, ensure you instantiate them at runtime.

Shipping methods will be reworked for Oscar 0.7 to avoid these issues.

Now that products can have multiple stockrecords, several changes have been made
to baskets to allow the appropriate stockrecord to be tracked for each basket
line. The basket line model has a new field that links to the selected
stockrecord and the basket itself requires an instance of the strategy class so
that prices can be calculated for each line. Hence, if you loading baskets
and manipulating baskets directly, you need to assign a strategy class in order
for prices to calculate correctly:

There are rather a lot of new migrations in Oscar 0.6. They are all detailed
below.

If you are upgrading and your project overrides one of these apps with
new migrations, then ensure you pick up the schema changes in a new migration
within your app. You can generally do this using manage.pyschemamigration$APP--auto but check the corresponding core migration to ensure there aren’t
any subtleties that are being overlooked.

Some of these migrations rename fields for consistency, while others ensure
CharField fields are not nullable.

Address:

0003: A new field display_order is added to the Country
model. This is the first of 3 migrations that replace the
boolean is_highlighted field with an integer field that allows
fine-grained control of the order of countries in dropdowns.

0004: A data migration to ensure highlighted countries have a display
order of 1.

0005: Remove the is_highlighted field from the Country model
as it is no longer necessary.

0006: Add a uniqueness constraint across user_id and hash for
the UserAddress model to prevent duplicate addresses.

0007: Use a custom field for address postcodes.

Basket:

0004: Add stockrecord field to the Line model to track which
stockrecord has been selected to fulfill a particular line.

0005: Add price_currency field to the Line model.

Catalogue:

0011: Larger max_length on FileFields and ImageFields

0012: Use NullBooleanField for the value_boolean field of
the ProductAttributeValue model.

0013: Add value_file and value_image fields to the
ProductAttributeValue model to support file and image attributes.

Customer:

0005: Don’t allow sms_template field of
CommunicationEventType model to be nullable.

Dashboard:

0002: Don’t allow error_message field of
RangeProductFileUpload model to be nullable.

The stockrecord property is
deprecated since it presumes there is only one stockrecord per product.
Choosing the appropriate stockrecord is now the responsibility of the
strategy class. A backward compatible version has
been kept in place that selects the first stockrecord for a product. This
will continue to work for sites that only have one stockrecord per product.

The shipping_method method of the
CheckoutSessionData is now deprecated in
favour of using shipping_method_code. It is being removed as the
CheckoutSessionData class should only be responsible for retrieving data
from the session, not loading shipping method instances.

Before Oscar 0.6, availability and pricing logic was encapsulated in “partner
wrappers”. A partner wrapper was a class that provided availability and price
information for a particular partner, as specified by the
OSCAR_PARTNER_WRAPPERS setting. The stockrecord model had several
properties and methods
which delegated to the appropriate wrapper for the record’s partner.

This functionality is now deprecated in favour of using strategy classes.
How prices and taxes are determined is not generally a function of the partner,
and so this system was not a good model. Strategy classes are much more
flexible and allow better modelling of taxes and availability.

The following properties and methods from StockRecord
are deprecated and will be removed for Oscar 0.7. These are all convenience
properties and methods that delegate to the appropriate partner wrapper.

All the above properties and methods have effectively been moved to the availability and pricing
policies that a strategy class is responsible for loading. To upgrade your
codebase, replace your partner wrapper classes with equivalent
availability and pricing policies.

The Oscar test support library has been ported back into Oscar core. This
simplifies things and avoids circular dependency issues. If your project is
using this extension, you should remove it as a dependency and use the
analogous functionality from oscar/test/.