Split up contributing guidelines

They were getting quite long. They've been split up in several
subsections. Some of them are borrowing heavily from the Django docs.

CONTRIBUTING.rst

@@ -1,262 +1,7 @@
-============
-Contributing
-============
+=====================
+Contributing to Oscar
+=====================
 
-Some ground rules:
+Thank you for wanting to contribute! You can find detailed guidance in the repository at ``docs/source/internals/contributing``, or online at:
 
-* To avoid disappointment, new features should be discussed on the mailing list
-  (django-oscar@googlegroups.com) before serious work starts. 
-
-* Write tests! Pull requests will be rejected if sufficient tests aren't
-  provided.  See the guidance below on the testing conventions that Oscar uses.
-
-* Write docs! Please update the documentation when altering behaviour or introducing new features.
-
-* Write good commit messages: see `Tim Pope's excellent note`_.
-
-.. _`Tim Pope's excellent note`: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
-
-* Make pull requests against Oscar's master branch unless instructed otherwise.
-
-Installation
-============
-
-After forking, run::
-
-    git clone git@github.com:<username>/django-oscar.git
-    cd django-oscar
-    mkvirtualenv oscar  # using virtualenvwrapper
-    make install
-
-Running tests
-=============
-
-Oscar uses a nose_ testrunner which can be invoked using::
-
-    ./runtests.py
-
-.. _nose: http://nose.readthedocs.org/en/latest/
-
-To run a subset of tests, you can use filesystem or module paths.  These two
-commands will run the same set of tests::
-
-    ./runtests.py tests/unit/order
-    ./runtests.py tests.unit.order
-
-To run an individual test class, use one of::
-
-    ./runtests.py tests/unit/order:TestSuccessfulOrderCreation
-    ./runtests.py tests.unit.order:TestSuccessfulOrderCreation
-
-(Note the ':'.)
-
-To run an individual test, use one of::
-
-    ./runtests.py tests/unit/order:TestSuccessfulOrderCreation.test_creates_order_and_line_models
-    ./runtests.py tests.unit.order:TestSuccessfulOrderCreation.test_creates_order_and_line_models
-
-Oscar's testrunner uses the progressive_ plugin when running all tests, but uses
-the spec_ plugin when running a subset.  It is a good practice to name your test
-cases and methods so that the spec output reads well.  For example::
-
-    $ ./runtests.py tests/unit/offer/benefit_tests.py:TestAbsoluteDiscount
-    nosetests --verbosity 1 tests/unit/offer/benefit_tests.py:TestAbsoluteDiscount -s -x --with-spec
-    Creating test database for alias 'default'...
-
-    Absolute discount
-    - consumes all lines for multi item basket cheaper than threshold
-    - consumes all products for heterogeneous basket
-    - consumes correct quantity for multi item basket more expensive than threshold
-    - correctly discounts line
-    - discount is applied to lines
-    - gives correct discount for multi item basket cheaper than threshold
-    - gives correct discount for multi item basket more expensive than threshold
-    - gives correct discount for multi item basket with max affected items set
-    - gives correct discount for single item basket cheaper than threshold
-    - gives correct discount for single item basket equal to threshold
-    - gives correct discount for single item basket more expensive than threshold
-    - gives correct discounts when applied multiple times
-    - gives correct discounts when applied multiple times with condition
-    - gives no discount for a non discountable product
-    - gives no discount for an empty basket
-
-    ----------------------------------------------------------------------
-    Ran 15 tests in 0.295s
-
-.. _progressive: http://pypi.python.org/pypi/nose-progressive/
-.. _spec: http://darcs.idyll.org/~t/projects/pinocchio/doc/#spec-generate-test-description-from-test-class-method-names
-
-Playing in the sandbox
-======================
-
-Oscar ships with a 'sandbox' site which can be run locally to play around with
-Oscar using a browser.  Set it up by::
-
-   make sandbox 
-   cd sites/sandbox 
-   ./manage.py runserver
-
-This will create the database and load some fixtures for categories and shipping
-countries.
-
-Note that Oscar uses PIL_ and Sorl_ for thumbnailing, and so you will need
-``libjpeg-dev`` installed in your OS so that your PIL installation supports
-JPEGS.
-
-.. _PIL: http://www.pythonware.com/products/pil/
-.. _Sorl: http://sorl-thumbnail.readthedocs.org/en/latest/
-
-Vagrant
-=======
-
-Oscar ships with a Vagrant_ virtual machine that can be used to test integration
-with various services in a controlled environment.  For instance, it is used to
-test that the migrations run correctly in both MySQL and Postgres.
-
-.. _Vagrant: http://vagrantup.com/
-
-Building the Vagrant machine
-----------------------------
-
-To create the machine, first ensure that Vagrant and puppet_ are installed.  You will require a
-puppet version that supports ``puppet module install``, that is > 2.7.14.  Now
-run::
-
-    make puppet
-
-.. _puppet: http://docs.puppetlabs.com/guides/installation.html
-
-to fetch the required puppet modules for provisioning.  Finally, run::
-
-    vagrant up
-
-to create the virtual machine and provision it.
-
-Testing migrations against MySQL and Postgres
----------------------------------------------
-
-To test the migrations against MySQL and Postgres, do the following:
-
-1. SSH onto the VM::
-
-    vagrant ssh
-
-2. Change to sandbox folder and activate virtualenv::
-
-    cd /vagrant/sites/sandbox
-    source /var/www/virtualenv/bin/activate
-
-3. Run helper script::
-
-    ./test_migrations.sh
-
-    This will recreate the Oscar database in both MySQL and Postgres and rebuild
-    it using ``syncdb`` and ``migrate``.
-
-Testing WSGI server configurations
-----------------------------------
-
-You can browse the Oscar sandbox site in two ways:
-
-* Start Django's development server on port 8000::
-
-    vagrant ssh
-    cd /vagrant/sites/sandbox
-    source /var/www/virtualenv/bin/activate
-    ./manage.py runserver 0.0.0.0:8000
-
-  The Vagrant machine forwards port 8000 to post 8080 and so the site can be
-  accessed at http://localhost:8080 on your host machine.
-
-* The Vagrant machine install Apache2 and mod_wsgi.  You can browse the site
-  through Apache at http://localhost:8081 on your host machine.
-
-Writing LESS/CSS
-================
-
-The sandbox Oscar site defaults to serving the CSS files directly, bypassing
-LESS compilation.  If you want to develop the LESS files, set::
-
-    USE_LESS = True
-    COMPRESS_ENABLED = False
-
-in ``sites/sandbox/settings_local.py``.  You will also need to ensure that
-``lessc`` is installed.  This can be acheived by running::
-
-    pip install -r requirements_less.txt
-
-which will install the `virtual-node`_ and `virtual-less`_ packages, which will
-install node.js and LESS in your virtualenv.
-
-.. _`virtual-node`: https://github.com/elbaschid/virtual-node
-.. _`virtual-less`: https://github.com/elbaschid/virtual-less
-
-
-Writing docs
-============
-
-There's a helper script for building the docs locally::
-
-    cd docs
-    ./test_docs.sh
-
-The actual docs are in ``/docs/source``. This directory structure is a
-simplified version of what Django does.
-
-* ``internals/`` contains everything related to Oscar itself, e.g. contributing
-  guidelines or design philosophies.
-* ``ref/`` is the reference documentation, esp. consisting of
-* ``ref/apps/`` which should be a guide to each Oscar core app, explaining it's
-  function, the main models, how it relates to the other apps, etc.
-* ``topics/`` will contain "meta" articles, explaining how things tie together
-  over several apps, or how Oscar can be combined with other solutions.
-* ``howto/`` contains tutorial-style descriptions on how to solve a certain
-  problem. Ideally, those will be kept to a minimum; as the other docs should
-  be understandable enough that necessary steps to achieve a certain goal are
-  obvious.
-* ``_old/`` contains legacy documents that have not been moved into the new
-  structure. Please help get rid of those!
-
-``/index.rst`` is designed as the entry point, and diverges from above
-structure to make the documentation more approachable. Other ``index.rst``
-files should only be created if there's too many files to list them all.
-E.g. ``/index.rst`` directly links to all files in ``topics/`` and
-``internals/``, but there's an ``index.rst`` both for the files in ``howto/``
-and ``ref/apps/``.
-
-
-Conventions
-===========
-
-General
--------
-
-* PEP8 everywhere while remaining sensible
-
-URLs
-----
-
-* List pages should use plurals; e.g. ``/products/``, ``/notifications/``
-
-* Detail pages should simply be a PK/slug on top of the list page; e.g.
-  ``/products/the-bible/``, ``/notifications/1/``
-  
-* Create pages should have 'create' as the final path segment; e.g.
-  ``/dashboard/notifications/create/``
-
-* Update pages are sometimes the same as detail pages (i.e., 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; e.g., ``/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.
+http://django-oscar.readthedocs.org/en/latest/internals/contributing/index.html

docs/source/index.rst

@@ -90,5 +90,5 @@ Learn about the ideas behind Oscar and how you can contribute.
 .. toctree::
    :maxdepth: 1
 
-   internals/contributing
-   internals/design_decisions
+   internals/contributing/index
+   

docs/source/internals/contributing.rst

@@ -1 +0,0 @@
-../../../CONTRIBUTING.rst

docs/source/internals/contributing/bugs-and-features.rst

@@ -0,0 +1,81 @@
+======================================
+Reporting bugs and requesting features
+======================================
+
+Before reporting a bug or requesting a new feature, please consider these
+general points:
+
+* Check that someone hasn't already filed the bug or feature request by
+  searching in the ticket tracker.
+
+* Don't use the ticket system to ask support questions. Use the
+  `django-oscar`_ mailing list for that.
+
+* Don't use the ticket tracker for lengthy discussions, because they're
+  likely to get lost. If a particular ticket is controversial, please move the
+  discussion to `django-oscar`_.
+
+All bugs are reported on our `GitHub issue tracker`_.
+
+.. _`GitHub issue tracker`: https://github.com/tangentlabs/django-oscar/issues
+
+Reporting bugs
+--------------
+
+Well-written bug reports are *incredibly* helpful. However, there's a certain
+amount of overhead involved in working with any bug tracking system so your
+help in keeping our ticket tracker as useful as possible is appreciated. In
+particular:
+
+* **Do** ask on `django-oscar`_ *first* if you're not sure if
+  what you're seeing is a bug.
+
+* **Do** write complete, reproducible, specific bug reports. You must
+  include a clear, concise description of the problem, and a set of
+  instructions for replicating it. Add as much debug information as you can:
+  code snippets, test cases, exception backtraces, screenshots, etc. A nice
+  small test case is the best way to report a bug, as it gives us an easy
+  way to confirm the bug quickly.
+
+Reporting user interface bugs and features
+------------------------------------------
+
+If your bug or feature request touches on anything visual in nature, there
+are a few additional guidelines to follow:
+
+* Include screenshots in your ticket which are the visual equivalent of a
+  minimal testcase. Show off the issue, not the crazy customizations
+  you've made to your browser.
+
+* If you're offering a pull request which changes the look or behavior of
+  Oscar's UI, please attach before *and* after screenshots/screencasts.
+  
+* Screenshots don't absolve you of other good reporting practices. Make sure
+  to include URLs, code snippets, and step-by-step instructions on how to
+  reproduce the behavior visible in the screenshots.
+
+Requesting features
+-------------------
+
+We're always trying to make Oscar better, and your feature requests are a key
+part of that. Here are some tips on how to make a request most effectively:
+
+* First request the feature on the `django-oscar`_ list, not in the
+  ticket tracker. It'll get read more closely if it's on the mailing list.
+  This is even more important for large-scale feature requests. We like to
+  discuss any big changes to Oscar's core on the mailing list before
+  actually working on them.
+
+* Describe clearly and concisely what the missing feature is and how you'd
+  like to see it implemented. Include example code (non-functional is OK)
+  if possible.
+
+* Explain *why* you'd like the feature, because sometimes it isn't obvious 
+  why the feature would be useful.
+
+As with most open-source projects, code talks. If you are willing to write the
+code for the feature yourself or, even better, if you've already written it,
+it's much more likely to be accepted. Just fork Oscar on GitHub, create a
+feature branch, and show us your work!
+
+.. _django-oscar: http://groups.google.com/group/django-oscar

docs/source/internals/contributing/coding-style.rst

@@ -0,0 +1,36 @@
+============
+Coding Style
+============
+
+General
+-------
+
+* PEP8 everywhere while remaining sensible
+
+URLs
+----
+
+* List pages should use plurals; e.g. ``/products/``, ``/notifications/``
+
+* Detail pages should simply be a PK/slug on top of the list page; e.g.
+  ``/products/the-bible/``, ``/notifications/1/``
+  
+* Create pages should have 'create' as the final path segment; e.g.
+  ``/dashboard/notifications/create/``
+
+* Update pages are sometimes the same as detail pages (i.e., 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; e.g., ``/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.

docs/source/internals/design_decisions.rst → docs/source/internals/contributing/design-decisions.rst

@@ -1,6 +1,6 @@
-================
-Design decisions
-================
+======================
+Oscar Design Decisions
+======================
 
 The central aim of Oscar is to provide a solid core of an e-commerce project that can be
 extended and customised to suit the domain at hand.  This is achieved in several ways:

docs/source/internals/contributing/development-environment.rst

@@ -0,0 +1,115 @@
+======================================
+Setting up the development environment
+======================================
+
+Fork the repo and run::
+
+    git clone git@github.com:<username>/django-oscar.git
+    cd django-oscar
+    mkvirtualenv oscar  # using virtualenvwrapper
+    make install
+
+Playing in the sandbox
+======================
+
+Oscar ships with a 'sandbox' site which can be run locally to play around with
+Oscar using a browser. Set it up by::
+
+   make sandbox 
+   cd sites/sandbox 
+   ./manage.py runserver
+
+This will create the database and load some fixtures for categories and shipping
+countries.
+
+Note that Oscar uses PIL_ and Sorl_ for thumbnailing, and so you will need
+``libjpeg-dev`` installed in your OS so that your PIL installation supports
+JPEGS.
+
+.. _PIL: http://www.pythonware.com/products/pil/
+.. _Sorl: http://sorl-thumbnail.readthedocs.org/en/latest/
+
+Writing LESS/CSS
+================
+
+The sandbox Oscar site defaults to serving the CSS files directly, bypassing
+LESS compilation.  If you want to develop the LESS files, set::
+
+    USE_LESS = True
+    COMPRESS_ENABLED = False
+
+in ``sites/sandbox/settings_local.py``.  You will also need to ensure that
+``lessc`` is installed.  This can be acheived by running::
+
+    pip install -r requirements_less.txt
+
+which will install the `virtual-node`_ and `virtual-less`_ packages, which will
+install node.js and LESS in your virtualenv.
+
+.. _`virtual-node`: https://github.com/elbaschid/virtual-node
+.. _`virtual-less`: https://github.com/elbaschid/virtual-less
+
+Vagrant
+=======
+
+Oscar ships with a Vagrant_ virtual machine that can be used to test integration
+with various services in a controlled environment.  For instance, it is used to
+test that the migrations run correctly in both MySQL and Postgres.
+
+.. _Vagrant: http://vagrantup.com/
+
+Building the Vagrant machine
+----------------------------
+
+To create the machine, first ensure that Vagrant and puppet_ are installed.  You will require a
+puppet version that supports ``puppet module install``, that is > 2.7.14.  Now
+run::
+
+    make puppet
+
+.. _puppet: http://docs.puppetlabs.com/guides/installation.html
+
+to fetch the required puppet modules for provisioning.  Finally, run::
+
+    vagrant up
+
+to create the virtual machine and provision it.
+
+Testing migrations against MySQL and Postgres
+---------------------------------------------
+
+To test the migrations against MySQL and Postgres, do the following:
+
+1. SSH onto the VM::
+
+    vagrant ssh
+
+2. Change to sandbox folder and activate virtualenv::
+
+    cd /vagrant/sites/sandbox
+    source /var/www/virtualenv/bin/activate
+
+3. Run helper script::
+
+    ./test_migrations.sh
+
+    This will recreate the Oscar database in both MySQL and Postgres and rebuild
+    it using ``syncdb`` and ``migrate``.
+
+Testing WSGI server configurations
+----------------------------------
+
+You can browse the Oscar sandbox site in two ways:
+
+* Start Django's development server on port 8000::
+
+    vagrant ssh
+    cd /vagrant/sites/sandbox
+    source /var/www/virtualenv/bin/activate
+    ./manage.py runserver 0.0.0.0:8000
+
+  The Vagrant machine forwards port 8000 to post 8080 and so the site can be
+  accessed at http://localhost:8080 on your host machine.
+
+* The Vagrant machine install Apache2 and mod_wsgi.  You can browse the site
+  through Apache at http://localhost:8081 on your host machine.

docs/source/internals/contributing/index.rst

@@ -0,0 +1,41 @@
+=====================
+Contributing to Oscar
+=====================
+
+You're thinking of helping out. That's brilliant - thank you for your time! You can contribute in many ways:
+
+* Join the `django-oscar`_ mailing list and answer questions.
+
+.. _django-oscar: http://groups.google.com/group/django-oscar
+
+* :doc:`Report bugs <bugs-and-features>` in our `ticket tracker`_.
+
+.. _ticket tracker: https://github.com/tangentlabs/django-oscar/issues
+
+* :doc:`Submit pull requests <submitting-pull-requests>` for new and/or
+  fixed behavior.
+
+* :doc:`Improve the documentation <writing-documentation>`.
+
+* :doc:`Write tests <running-tests>`.
+
+* Translations can be contributed using Transifex_. Just apply for a language
+  and go ahead!
+
+.. _Transifex: https://www.transifex.com/projects/p/django-oscar/
+
+
+
+Overview
+--------
+
+.. toctree::
+   :maxdepth: 1
+   
+   development-environment
+   bugs-and-features
+   coding-style
+   design-decisions
+   submitting-pull-requests
+   running-tests
+   writing-documentation

docs/source/internals/contributing/running-tests.rst

@@ -0,0 +1,58 @@
+=============
+Running tests
+=============
+
+Oscar uses a nose_ testrunner which can be invoked using::
+
+    ./runtests.py
+
+.. _nose: http://nose.readthedocs.org/en/latest/
+
+To run a subset of tests, you can use filesystem or module paths.  These two
+commands will run the same set of tests::
+
+    ./runtests.py tests/unit/order
+    ./runtests.py tests.unit.order
+
+To run an individual test class, use one of::
+
+    ./runtests.py tests/unit/order:TestSuccessfulOrderCreation
+    ./runtests.py tests.unit.order:TestSuccessfulOrderCreation
+
+(Note the ':'.)
+
+To run an individual test, use one of::
+
+    ./runtests.py tests/unit/order:TestSuccessfulOrderCreation.test_creates_order_and_line_models
+    ./runtests.py tests.unit.order:TestSuccessfulOrderCreation.test_creates_order_and_line_models
+
+Oscar's testrunner uses the progressive_ plugin when running all tests, but uses
+the spec_ plugin when running a subset.  It is a good practice to name your test
+cases and methods so that the spec output reads well.  For example::
+
+    $ ./runtests.py tests/unit/offer/benefit_tests.py:TestAbsoluteDiscount
+    nosetests --verbosity 1 tests/unit/offer/benefit_tests.py:TestAbsoluteDiscount -s -x --with-spec
+    Creating test database for alias 'default'...
+
+    Absolute discount
+    - consumes all lines for multi item basket cheaper than threshold
+    - consumes all products for heterogeneous basket
+    - consumes correct quantity for multi item basket more expensive than threshold
+    - correctly discounts line
+    - discount is applied to lines
+    - gives correct discount for multi item basket cheaper than threshold
+    - gives correct discount for multi item basket more expensive than threshold
+    - gives correct discount for multi item basket with max affected items set
+    - gives correct discount for single item basket cheaper than threshold
+    - gives correct discount for single item basket equal to threshold
+    - gives correct discount for single item basket more expensive than threshold
+    - gives correct discounts when applied multiple times
+    - gives correct discounts when applied multiple times with condition
+    - gives no discount for a non discountable product
+    - gives no discount for an empty basket
+
+    ----------------------------------------------------------------------
+    Ran 15 tests in 0.295s
+
+.. _progressive: http://pypi.python.org/pypi/nose-progressive/
+.. _spec: http://darcs.idyll.org/~t/projects/pinocchio/doc/#spec-generate-test-description-from-test-class-method-names

docs/source/internals/contributing/submitting-pull-requests.rst

@@ -0,0 +1,17 @@
+========================
+Submitting pull requests
+========================
+
+* To avoid disappointment, new features should be discussed on the mailing list
+  (django-oscar@googlegroups.com) before serious work starts. 
+
+* Write tests! Pull requests will be rejected if sufficient tests aren't
+  provided. 
+
+* Write docs! Please update the documentation when altering behaviour or introducing new features.
+
+* Write good commit messages: see `Tim Pope's excellent note`_.
+
+.. _`Tim Pope's excellent note`: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+
+* Make pull requests against Oscar's master branch unless instructed otherwise.

docs/source/internals/contributing/writing-documentation.rst

@@ -0,0 +1,24 @@
+=====================
+Writing documentation
+=====================
+
+The docs are built by calling ``make docs`` from your Oscar directory.
+They live in ``/docs/source``. This directory structure is a
+simplified version of what Django does.
+
+* ``internals/`` contains everything related to Oscar itself, e.g. contributing
+  guidelines or design philosophies.
+* ``ref/`` is the reference documentation, esp. consisting of
+* ``ref/apps/`` which should be a guide to each Oscar core app, explaining it's
+  function, the main models, how it relates to the other apps, etc.
+* ``topics/`` will contain "meta" articles, explaining how things tie together
+  over several apps, or how Oscar can be combined with other solutions.
+* ``howto/`` contains tutorial-style descriptions on how to solve a certain
+  problem.
+
+``/index.rst`` is designed as the entry point, and diverges from above
+structure to make the documentation more approachable. Other ``index.rst``
+files should only be created if there's too many files to list them all.
+E.g. ``/index.rst`` directly links to all files in ``topics/`` and
+``internals/``, but there's an ``index.rst`` both for the files in ``howto/``
+and ``ref/apps/``.

docs/source/internals/getting_help.rst

@@ -10,7 +10,9 @@ 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`_
+If you think you found a bug, please read
+:doc:`Reporting bugs <contributing/bugs-and-features>` and report it
+in the `GitHub issue tracker`_.
 
 .. _`GitHub issue tracker`: https://github.com/tangentlabs/django-oscar/issues
 

docs/source/ref/apps/index.rst

@@ -1,6 +1,6 @@
-===============
-Oscar Core Apps
-===============
+=========================
+Oscar Core Apps explained
+=========================
 
 Oscar is split up in multiple, mostly independent apps.
 

setup.py

@@ -73,7 +73,7 @@ setup(name='django-oscar',
 
 # Show contributing instructions if being installed in 'develop' mode
 if len(sys.argv) > 1 and sys.argv[1] == 'develop':
-    docs_url = 'http://django-oscar.readthedocs.org/en/latest/contributing.html'
+    docs_url = 'http://django-oscar.readthedocs.org/en/latest/internals/contributing/index.html'
     mailing_list = 'django-oscar@googlegroups.com'
     mailing_list_url = 'https://groups.google.com/forum/?fromgroups#!forum/django-oscar'
     twitter_url = 'https://twitter.com/django_oscar'