Skip to content

E
ecommerce
Commit 1daeba17 by Renzo Lucioni
Options

Clean up README 

Create new docs sections for asset pipeline and email notifications, extend existing sections with content from README.
parent 0f322f7c
Showing with 67 additions and 155 deletions
README.rst
......@@ -21,156 +21,6 @@ Documentation |ReadtheDocs|_
`Documentation <https://open-edx-ecommerce-guide.readthedocs.org/en/latest/>`_ is hosted on Read the Docs.
Getting Started
---------------
Most commands necessary to run and develop the ecommerce service can be found in the included Makefile.
1. Install the Python/Node/Bower requirements for local development::
$ make requirements
Note: If you want to install only the production requirements run ``pip install -r requirements/production.txt``.
2. Setup the database::
$ make migrate
3. Populate the countries tables (used for storing addresses)::
$ python manage.py oscar_populate_countries
4. Run the development server::
$ make serve
Django Debug Toolbar is disabled by default. Enable it by setting the environment variable ENABLE_DJANGO_TOOLBAR.
Alternatively, you can launch the server using:
$ ENABLE_DJANGO_TOOLBAR=1 make serve
Asset Pipeline
--------------
Static files are managed via `django-compressor`_ and `RequireJS`_ (and r.js) are used to manage JavaScript dependencies.
django-compressor compiles SASS, minifies JavaScript, and handles naming files to facilitate cache busting during deployment.
.. _django-compressor: http://django-compressor.readthedocs.org/
.. _RequireJS: http://requirejs.org/
Both tools should operate seamlessly in a local development environment. When deploying to production, call
``make static`` to compile all static assets and move them to the proper location to be served.
When creating new pages that utilize RequireJS dependencies, remember new modules to ``build.js``.
NOTE: The static file directories are setup such that the build output directory of ``r.js`` is read before checking
for assets in ``ecommerce\static\``. If you run ``make static`` or ``r.js`` locally (which you should not need to),
make sure you delete ``ecommerce/static/build`` or run ``make static`` before continuing with development. If you do not
all changes made to static files will be ignored.
Feature Switches
----------------
This app uses `Waffle`_ to manage feature gating/switching. Switches can be managed via Django admin. The following
switches exist:
+--------------------------------+---------------------------------------------------------------------------+
| Name | Functionality |
+================================+=======================+===================================================+
| user_enrollments_on_dashboard | Display a user's current enrollments on the dashboard user detail page |
+--------------------------------+---------------------------------------------------------------------------+
| publish_course_modes_to_lms | Publish prices and SKUs to the LMS after every course modification |
+--------------------------------+---------------------------------------------------------------------------+
| ENABLE_CREDIT_APP | Enable the credit checkout page from where student's can purchase credit |
| | courses. |
+--------------------------------+---------------------------------------------------------------------------+
| ENABLE_NOTIFICATIONS | Enable email notification for the different task generated e.g. course |
| | purchase. |
+--------------------------------+---------------------------------------------------------------------------+
| PAYPAL_RETRY_ATTEMPTS | Enable retry mechanism for failed PayPal payment executions. |
+--------------------------------+---------------------------------------------------------------------------+
.. _Waffle: https://waffle.readthedocs.org/
Analytics
---------
To use google analytics for specific events e.g., button clicks, you need to add the segment key into the settings
file:
``SEGMENT_KEY = 'your segment key'``
Credit
------
To enable custom credit checkout page, please add the following waffle switch:
``ENABLE_CREDIT_APP``
Notification
------------
To create and send email notifications for a task, we use `Communications API <http://django-oscar.readthedocs.org/en/latest/howto/how_to_customise_oscar_communications.html#communications-api>`_:
1. First you need to define an arbitrary ``Communication Type Code`` that would be use to refer a particular type
of notification. For example, ``Communication Type Code`` used for the course purchased would be ``COURSE_PURCHASED``.
2. Create three template files (HTML, plain text, subject) associated with the email in directory ``ecommerce/ecommerce/templates/customer/emails/``.
Note that the naming convention should be something like ``commtype_{Communication Type Code}_body.html``
For example for ``COURSE_PURCHASED`` code template file names will be ``commtype_course_purchased_body.html``,
``commtype_course_purchased_body.txt`` and ``commtype_course_purchased_subject.txt``. The HTML file should
extend ``email_base.html`` for basic styling. You can override ``block body`` (must) and ``block footer``(optionally)
to add your custom email body and custom footer respectively.
3. Use the method ``send_notification(user, commtype_code, context)``, implemented in ``ecommerce/ecommerce/notifications/notifications.py``.
For more information please read method docstring.
Testing
-------
To run the unit test suite followed by quality checks, run::
$ make validate
To run only Python unit tests, run:
::
$ make validate_python
To run only JavaScript unit tests, run:
::
$ make validate_js
JavaScript Unit Testing
~~~~~~~~~~~~~~~~~~~~~~~
This project uses `Jasmine <http://jasmine.github.io/2.3/introduction.html>`__ for JavaScript unit testing.
Tests should be placed in the ecommerce/static/js/test/specs directory, and suffixed with _spec
(e.g. ecommerce/static/js/test/specs/course_list_view_spec.js).
Additionally, all JavaScript code should adhere to the `edX JavaScript standards <https://github.com/edx/edx-platform/wiki/Javascript-standards-for-the-edx-platform>`__.
These standards are enforced using `JSHint <http://www.jshint.com/>`__ and `jscs <https://www.npmjs.org/package/jscs>`__.
Tests and linting can be run with the following command:
::
$ make validate_js
Acceptance Testing
~~~~~~~~~~~~~~~~~~
For instructions on how to run the acceptance tests, please consult the
README file located in the `acceptance tests README`_.
.. _acceptance tests README: acceptance_tests/README.rst
License
-------
......
docs/asset_pipeline.rst 0 → 100644
Asset Pipeline
==============
Static files are managed via `django-compressor`_. `RequireJS`_ and r.js are used to manage JavaScript dependencies.
django-compressor compiles SASS, minifies JavaScript, and handles naming files to facilitate cache busting during deployment.
.. _django-compressor: http://django-compressor.readthedocs.org/
.. _RequireJS: http://requirejs.org/
Both tools should operate seamlessly in a local development environment. When deploying to production, call
``make static`` to compile all static assets and move them to the proper location to be served.
When creating new pages that utilize RequireJS dependencies, remember new modules to ``build.js``.
NOTE: The static file directories are setup such that the build output directory of ``r.js`` is read before checking
for assets in ``ecommerce\static\``. If you run ``make static`` or ``r.js`` locally (which you should not need to),
make sure you delete ``ecommerce/static/build`` or run ``make static`` before continuing with development. If you do not
all changes made to static files will be ignored.
docs/features.rst
Feature Toggling
================
All new features/functionality should be released behind a feature gate. This allows us to easily disable features
in the event that an issue is discovered in production. This project uses the
`Waffle <http://waffle.readthedocs.org/en/latest/>`_ library for feature gating.
Waffle supports three types of feature gates (listed below). We typically use flags and switches since samples are
random, and not ideal for our needs.
random and not ideal for our needs.
Flag
Enable a feature for specific users, groups, users meeting certain criteria (e.g. authenticated or staff),
......@@ -21,6 +22,34 @@ random, and not ideal for our needs.
For information on creating or updating features, refer to the
`Waffle documentation <http://waffle.readthedocs.org/en/latest/>`_.
Available Switches
------------------
Switches can be managed via the Django admin. The following switches exist:
+--------------------------------+---------------------------------------------------------------------------+
| Name | Functionality |
+================================+=======================+===================================================+
| user_enrollments_on_dashboard | Display a user's current enrollments on the dashboard user detail page |
+--------------------------------+---------------------------------------------------------------------------+
| publish_course_modes_to_lms | Publish prices and SKUs to the LMS after every course modification |
+--------------------------------+---------------------------------------------------------------------------+
| async_order_fulfillment | Fulfill orders asynchronously |
+--------------------------------+---------------------------------------------------------------------------+
| ENABLE_CREDIT_APP | Enable the credit checkout page, from which students can purchase credit |
| | courses |
+--------------------------------+---------------------------------------------------------------------------+
| ENABLE_NOTIFICATIONS | Enable email notifications for a variety of user actions (e.g., order |
| | placed) |
+--------------------------------+---------------------------------------------------------------------------+
| PAYPAL_RETRY_ATTEMPTS | Enable retry mechanism for failed PayPal payment executions |
+--------------------------------+---------------------------------------------------------------------------+
Business Intelligence (Analytics)
---------------------------------
We use `Segment <https://segment.com/>`_ to collect business intelligence data. Specify a value for ``SEGMENT_KEY`` in settings to emit events to the corresponding Segment project.
Permanent Feature Rollout
-------------------------
Over time some features may become permanent and no longer need a feature gate around them. In such instances, the
......
docs/index.rst
......@@ -12,11 +12,13 @@ These are the developer docs for the edX E-Commerce Service.
:maxdepth: 2
getting_started
partner_config
asset_pipeline
testing
features
internationalization
partner_config
fulfillment
notifications
internationalization
TODO
- Oscar Dashboard
......
docs/notifications.rst 0 → 100644
Notifications
=============
We use Oscar's `Communications API <http://django-oscar.readthedocs.org/en/latest/howto/how_to_customise_oscar_communications.html#communications-api>`_ to create and send email notifications. If you've enabled the feature, you may define arbitrary "Communication Type Codes" used to refer to particular types of notification. For example, the Communication Type Code corresponding to the purchase of a course seat might be ``COURSE_SEAT_PURCHASED``.
Each email requires the presence of three files: an HTML template, a plain text file containing the email's subject line, and a plain text file containing the email's body. The files should be placed in ``ecommerce/ecommerce/templates/customer/emails/``. You should adhere to the following naming convention: ``commtype_{Communication Type Code}_body.html``. For example, an email related to the purchase of a course seat should have template file named ``commtype_course_seat_purchased_body.html``, ``commtype_course_seat_purchased_body.txt``, and ``commtype_course_seat_purchased_subject.txt``. The HTML template should extend ``email_base.html``. Override ``block body`` to add a custom email body and, optionally, ``block footer`` to add a custom footer.
To actually send emails, use the method ``send_notification(user, commtype_code, context)``, implemented in ``ecommerce/ecommerce/notifications/notifications.py``.
docs/testing.rst
Testing
=======
The command below runs the Python tests and code quality validation—Pylint and PEP8.
To run the unit test suite followed by quality checks, run:
.. code-block:: bash
$ make validate
Code quality validation can be run independently with:
Code quality validation can be performed independently with:
.. code-block:: bash
......@@ -139,3 +139,8 @@ As discussed above, the acceptance tests rely on configuration which can be spec
When running against a production-like staging environment, you might run::
$ ECOMMERCE_URL_ROOT="https://ecommerce.stage.edx.org" LMS_URL_ROOT="https://courses.stage.edx.org" LMS_USERNAME="<username>" LMS_EMAIL="<email address>" LMS_PASSWORD="<password>" ACCESS_TOKEN="<access token>" LMS_HTTPS="True" LMS_AUTO_AUTH="False" PAYPAL_EMAIL="<email address>" PAYPAL_PASSWORD="<password>" BASIC_AUTH_USERNAME="<username>" BASIC_AUTH_PASSWORD="<password>" HONOR_COURSE_ID="<course ID>" VERIFIED_COURSE_ID="<course ID>" make accept
JavaScript Testing
------------------
This project uses `Jasmine <http://jasmine.github.io/2.3/introduction.html>`_ for JavaScript unit testing. Tests should be placed in ``ecommerce/static/js/test/specs`` and suffixed with ``_spec``. For example, ``ecommerce/static/js/test/specs/course_list_view_spec.js``. All JavaScript code should adhere to the `edX JavaScript standards <https://github.com/edx/edx-platform/wiki/Javascript-standards-for-the-edx-platform>`_. These standards are enforced using `JSHint <http://www.jshint.com/>`_ and `jscs <https://www.npmjs.org/package/jscs>`_.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment