django-oscar · roadsideseb · May 21, 2012 · May 21, 2012 · May 21, 2012 · May 24, 2012
diff --git a/.gitignore b/.gitignore
@@ -31,3 +31,5 @@ TODO
 .coverage
 htmlcov/*
 sandbox/public/
+logs/
+build/
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -2,34 +2,33 @@
 Changelog
 =========
 
-0.1
-~~~
+0.2 - 01 June 2012
+~~~~~~~~~~~~~~~~~~
 
-* Initial release - used in production by two major applications at Tangent but
-  still quite rough around the edges.  Many features were implemented directly
-  in the applications rather than using a feature from oscar.
-* Docs are a bit stale and need updating in 0.2
+Many components have been rewritten since 0.1 - Oscar is much more of a complete
+package now.  New features include:
 
-Roadmap
--------
+* Dashboard for managing catalogue, offers, stock, vouchers and more.  This includes
+  statistics pages to track performance.
 
-0.2
-~~~
+* Sample templates, CSS and JS to get a shop up and running in a minutes.  
+
+* Updated documentation.
 
-Currently a work-in-progress, estimated release date: May 2012.  It will feature:
+* Reworking of shipping methods.
 
-* Much better documentation, including recipes for common tasks
-* Refactoring of shipping methods
-* New dashboard functionality for product management, order management, customer services
-* New dynamic class loading
-* Lots more tests!
-* A fully styled sandbox shop based on Twitter's bootstrap.
+* Automatic up-selling on the basket page.  We now inform the user if they
+  partially qualify for an offer.
 
-0.3
+The documentation still needs more work which we'll do over the next week or
+two.
+
+0.1
 ~~~
 
-* Rewrite of search app to use Solr and probably not Haystack
-* Much better support for variant products which aren't handled very well at the
-  moment.
-* Dashboard issue management
-* Better support for role-based permissions
+* Initial release - used in production by two major applications at Tangent but
+  still quite rough around the edges.  Many features were implemented directly
+  in the applications rather than using a feature from oscar.
+
+* Docs are a bit stale and need updating in 0.2
+
diff --git a/README.rst b/README.rst
@@ -10,37 +10,49 @@ core functionality can be customised to suit the needs of your project.  This
 allows it to handle a wide range of e-commerce requirements, from large-scale B2C
 sites to complex B2B sites rich in domain-specific business logic.
 
-Oscar is used in production by:
-
-* Tata - http://www.landmarkonthenet.com
-* Carlsberg's global business platform is powered by Oscar.
-* Dolbeau - http://www.dolbeau.ca/
-* The UK Labour party
-
 This README is just a stub - see the following links for more details
 information:
 
 * `Official homepage`_ 
 * `Demo site`_ (experimental) 
 * `Documentation`_ on `readthedocs.org`_
+* `Google Group`_ - the mailing list is django-oscar@googlegroups.com
 * `Continuous integration homepage`_ on `travis-ci.org`_
 * `Twitter account for news and updates`_
 * `Twitter account of all commits`_
 
 .. image:: https://secure.travis-ci.org/tangentlabs/django-oscar.png
 
-.. _`Official homepage`: http://tangentlabs.github.com/django-oscar/
+.. _`Official homepage`: http://oscarcommerce.com
 .. _`Demo site`: http://sandbox.oscar.tangentlabs.co.uk
 .. _`Documentation`: http://django-oscar.readthedocs.org/en/latest/
 .. _`readthedocs.org`: http://readthedocs.org
 .. _`Continuous integration homepage`: http://travis-ci.org/#!/tangentlabs/django-oscar 
 .. _`travis-ci.org`: http://travis-ci.org/
 .. _`Twitter account for news and updates`: https://twitter.com/#!/django_oscar
 .. _`Twitter account of all commits`: https://twitter.com/#!/oscar_django
+.. _`Google Group`: https://groups.google.com/forum/?fromgroups#!forum/django-oscar
 
 Oscar was written by `David Winterbottom`_ (`@codeinthehole`_) and is developed
 and maintained by `Tangent Labs`_, a London-based digital agency.
 
+Oscar is released under the permissive `New BSD license`_.
+
 .. _`David Winterbottom`: http://codeinthehole.com
 .. _`@codeinthehole`: https://twitter.com/codeinthehole
 .. _`Tangent Labs`: http://www.tangentlabs.co.uk
+.. _`New BSD license`: https://github.com/tangentlabs/django-oscar/blob/master/LICENSE
+
+Case studies
+------------
+
+Oscar is still in active development, but is used in production by a range of
+companies, from large multinationals to small, boutique stores:
+
+* Tata Group - http://www.landmarkonthenet.com
+* Carlsberg - Their global "We Deliver More" platform is powered by Oscar (but
+  is a B2B site so it not browsable by the public).
+* Dolbeau - http://www.dolbeau.ca/
+* The UK Labour party - http://shop.labour.org.uk (will be live in early June)
+
+Many more on the way.
diff --git a/docs/source/_draft/getting_started/installation.rst b/docs/source/_draft/getting_started/installation.rst
@@ -21,38 +21,38 @@ Create a new virtual env::
 A nice extension now is to edit your ``~/.virtualenv/$PROJECTNAME/bin/postactivate`` file to contain::
 
     cd ~/path/to/my/workspace/$PROJECTNAME
-    
+
 so that you can simply type ``workon $PROJECTNAME`` to jump into your project folder with the virtual
 environment set-up.
 
 Installation
 ------------
-    
-Install oscar and its dependencies::    
-    
+
+Install oscar and its dependencies::
+
     pip install -e git+git://github.com/tangentlabs/django-oscar.git#egg=django-oscar
-    
+
 You will also need to install the appropriate python module for your database of choice.
 If you are using MySQL, then run the following::
 
     pip install MySQL-python
 
-Also, depending on your search backend for haystack, you'll need to install further 
+Also, depending on your search backend for haystack, you'll need to install further
 packages::
 
     pip install pysolr
 
 Now create the project::
-    
+
     cd /path/to/my/workspace
     django-admin.py startproject $PROJECTNAME
 
 Configure ``settings.py``
 -------------------------
 
-* Add ``'django.middleware.transaction.TransactionMiddleware'`` to your ``MIDDLEWARE_CLASSES`` tuple, making 
+* Add ``'django.middleware.transaction.TransactionMiddleware'`` to your ``MIDDLEWARE_CLASSES`` tuple, making
   sure it comes AFTER ``'django.contrib.auth.middleware.AuthenticationMiddleware'``.
-  
+
 * Add the following to your `INSTALLED_APPS`::
 
     'haystack',
@@ -75,25 +75,26 @@ Configure ``settings.py``
     'oscar.apps.reports',
     'oscar.apps.search',
     'oscar.apps.catalogue_import',
-
+
+
 * Add these to ``TEMPLATE_CONTECT_PROCESSORS``::
 
     'oscar.apps.search.context_processors.search_form',
     'oscar.apps.promotions.context_processors.promotions',
-    'oscar.apps.promotions.context_processors.merchandising_blocks',    
-    
+    'oscar.apps.promotions.context_processors.merchandising_blocks',
+
 * Import default settings::
 
     from oscar.defaults import *
-    
+
 * If using Solr, configure it::
 
     HAYSTACK_SITECONF = 'oscar.search_sites'
     HAYSTACK_SEARCH_ENGINE = 'solr'
     HAYSTACK_SOLR_URL = 'http://127.0.0.1:8080/solr'
     HAYSTACK_INCLUDE_SPELLING = True
-    
-Now fill in the normal settings (not related to django-oscar) within ``settings.py`` - eg ``DATABASES``, ``TIME_ZONE`` etc    
+
+Now fill in the normal settings (not related to django-oscar) within ``settings.py`` - eg ``DATABASES``, ``TIME_ZONE`` etc
 
 A vanilla install of django-oscar is now ready, you could now finish the process by running::
 

diff --git a/docs/source/components.rst b/docs/source/components.rst
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
@@ -2,15 +2,69 @@
 Contributing
 ============
 
-* New features should be discussed on the mailing list (or in the meetings) before serious work starts
-* Pull requests will be rejected if sufficient tests aren't provided
-* Please update the documentation when altering behaviour or introducing new features 
+Some ground rules:
 
-Contents:
+* To avoid disappointment, new features should be discussed on the mailing list
+  (django-oscar@googlegroups.com) before serious work starts.
 
-.. toctree::
-   :maxdepth: 2
+* Pull requests will be rejected if sufficient tests aren't provided.
 
-   contributing/installation
-   contributing/testing
-   contributing/conventions
+* Please update the documentation when altering behaviour or introducing new features.
+
+* Follow the conventions (see below).
+
+Installation
+============
+
+From zero to tests passing in 2 minutes (most of which is PIL installing)::
+
+    git clone git@github.com:<username>/django-oscar.git
+    cd django-oscar
+    mkvirtualenv oscar
+    ./setup.py develop
+    pip install -r requirements.txt
+    ./run_tests.py
+
+Writing docs
+============
+
+There's a helper script for building the docs locally::
+
+    cd docs
+    ./test_docs.sh
+
+Conventions
+===========
+
+General
+-------
+
+* PEP8 everywhere while remaining sensible
+
+URLs
+----
+
+* List pages should use plurals, eg ``/products/``, ``/notifications/``
+
+* Detail pages should simply be a PK/slug on top of the list page, eg
+  ``/products/the-bible/``, ``/notifications/1/``
+
+* Create pages should have 'create' as the final path segment, eg
+  ``/dashboard/notifications/create/``
+
+* Update pages are sometimes the same as detail pages (ie when in the
+  dashboard).  In those cases, just use the detail convention, eg
+  ``/dashboard/notifications/3/``.  If there is a distinction between the detail
+  page and the update page, use ``/dashboard/notifications/3/update/``.
+
+* Delete pages, eg /dashboard/notifications/3/delete/
+
+View class names
+----------------
+
+Classes should be named according to::
+
+    '%s%sView' % (class_name, verb)
+
+For example, ``ProductUpdateView``, ``OfferCreateView`` and
+``PromotionDeleteView``.  This doesn't fit all situations but it's a good basis.
diff --git a/docs/source/customisation.rst → docs/source/design_decisions.rst b/docs/source/customisation.rst → docs/source/design_decisions.rst
@@ -8,9 +8,9 @@ extended and customised to suit the domain at hand.  This is acheived in several
 Core models are abstract
 ------------------------
 
-Online shops can vary wildly, selling everything from turnips to concert tickets.  Trying
-to define a set of Django models capable for modelling all such scenarios is impossible -
-customisation is what matters.
+Online shops can vary wildly, selling everything from turnips to concert
+tickets.  Trying to define a set of Django models capable for modelling all such
+scenarios is impossible - customisation is what matters.
 
 One way to model your domain is to have enormous models that have fields for
 every possible variation; however, this is unwieldy and ugly.  
@@ -24,35 +24,38 @@ where all the fields are meaningful within any e-commerce domain.  Oscar then
 provides a mechanism for subclassing these models within your application so
 domain-specific fields can be added.
 
-Specifically, in each of oscar's apps, there is an ``abstract_models.py`` module which
+Specifically, in many of oscar's apps, there is an ``abstract_models.py`` module which
 defines these abstract classes.  There is also an accompanying ``models.py`` which provides an
 empty but concrete implementation of each abstract model.
 
 Classes are loaded dynamically
 ------------------------------
 
 To enable sub-apps to be overridden, oscar classes are loading generically
-using a special ``import_module`` function.  This looks at the
+using a special ``get_class`` function.  This looks at the
 ``INSTALLED_APPS`` tuple to determine the appropriate app to load a class from.
 
-Within oscar itself, classes are imported using a special ``import_module`` function
-which determines which app to load the specified classes from.  Sample usage is::
+Sample usage::
 
-    import_module('product.models', ['Item', 'ItemClass'], locals())
+    from oscar.core.loading import get_class
+
+    Repository = get_class('shipping.repository', 'Repository')
 
-This will load the ``Item`` and ``ItemClass`` classes into the local namespace.  It is
-a replacement for the usual::
+This is a replacement for the usual::
+
+    from oscar.apps.shipping.repository import Repository
 
-    from oscar.product.models import Item, ItemClass
+It is effectively an extension of Django's ``django.db.models.get_model``
+function to work with arbitrary classes.
 
-The ``import_module`` looks through your ``INSTALLED_APPS`` for a matching module to
+The ``get_class`` function looks through your ``INSTALLED_APPS`` for a matching module to
 the one specified and will load the classes from there.  If the matching module is
 not from oscar's core, then it will also fall back to the equivalent module if the
 class cannot be found.
 
-This structure enables a project to create a local ``product.models`` module and 
-subclass and extend the core models from ``oscar.app.product.models``.  When Oscar
-tries to load the ``Item`` class, it will load the one from your local project.
+This structure enables a project to create a local ``shipping.repository`` module and 
+subclass and extend the classes from ``oscar.app.shipping.repository``.  When Oscar
+tries to load the ``Repository`` class, it will load the one from your local project.
 
 All views are class-based
 -------------------------

diff --git a/docs/source/getting_help.rst b/docs/source/getting_help.rst
@@ -0,0 +1,15 @@
+============
+Getting help
+============
+
+If you're stuck with a problem, try checking the `Google Groups archive`_ to see if
+someone has encountered it before.  If not, then try asking on the mailing list
+django-oscar@googlegroups.com.  If it's a common question, then we'll write up
+the solution as a recipe.
+
+.. _`Google Groups archive`: https://groups.google.com/forum/?fromgroups#!forum/django-oscar
+
+If you find a bug, please report it in the `Github issue tracker`_
+
+.. _`Github issue tracker`: https://github.com/tangentlabs/django-oscar/issues
+