docs: add the first ADRs (#55)

* docs: add the first ADRs

* docs: improve grammar and style

docs/source/decisions/0001-purpose-of-this-repo.rst

@@ -1,2 +1,50 @@
 1. Purpose of this Repo
 =======================
+
+Status
+******
+
+Accepted
+
+
+Context
+*******
+
+The Open edX community currently uses the e-commerce repo to manage commerce-related tasks. However, that repo is in `the process of being deprecated`_. 2U is building an extensible and pluggable next-generation commerce platform (commerce coordinator). However, this platform may be more complex and require more technical capabilities than all operators have. Therefore, `Axim looked for proposals for creating a WooCommerce Discovery`_ to have another way to sell Open edX courses easily.
+
+In that discovery (`WooCommerce Discovery`_), we realized we needed to create a Wordpress plugin that would connect the Open edX APIs with the WooCommerce orders in Wordpress. 
+
+Decision
+********
+
+- Have a WordPress plugin that allows the connection between Open edX and WooCommerce.
+
+
+Consequences
+************
+
+- We must install a WordPress plugin to sell Open edX courses with WooCommerce.
+- We need to maintain this plugin.
+
+
+Rejected Alternatives
+*********************
+
+- Use WooCommerce Webhooks: WooCommerce offers a natively supported way of managing webhooks. Still, the payload from a paid order did not include metadata that could be used to link the WooCommerce product to a course. It would have required then that the openedx plugin contained e-commerce information to link courses, programs, or discounts.
+
+- Maintain the Open edX eduNEXT extension in its current form: eduNEXT has published about five years ago with a similar plugin called `Open edX LMS and WordPress integrator`_. The code for this plugin is also available on GitHub. However, after years of supporting different initiatives using this plugin, we have concluded that the order handler needs to be more robust and built with a stronger foundation. Also, this plugin initially started as a way of making the information contained in the user-info cookie available to the menu header, and this and other such features grew organically into a plugin that needs to be better defined and focused. 
+
+
+References
+**********
+
+- `Ecommerce deprecation`_.
+- `Axim looked for proposals for creating a WooCommerce Discovery`_.
+- `WooCommerce Discovery`_.
+- `Open edX LMS and WordPress integrator`_.
+
+.. _the process of being deprecated: https://github.com/openedx/public-engineering/issues/22
+.. _Ecommerce deprecation: https://github.com/openedx/public-engineering/issues/22
+.. _Axim looked for proposals for creating a WooCommerce Discovery: https://discuss.openedx.org/t/tcril-funded-contribution-woocommerce-discovery/9337
+.. _WooCommerce Discovery: https://docs.google.com/document/d/1gImq4DFy3B_JSZlH3tCj5bmPQXji0OCnw1SbGB8bVxw/edit?usp=sharing
+.. _Open edX LMS and WordPress integrator: https://wordpress.org/plugins/edunext-openedx-integrator/

docs/source/decisions/0002-api-connection.rst

@@ -0,0 +1,57 @@
+2. API connection
+==================
+
+Status
+******
+
+Accepted
+
+
+Context
+*******
+
+We must connect this plugin with the available APIs in the Open edX platform to perform commerce actions raised in `Purpose of this repo`_.
+
+
+Decisions
+*********
+
+- This plugin uses the OAuth2 and JWT authentication following the standards in Open edX from the `OEP-42 Authentication`_.
+- To generate the JWT token, we use information such as client_id and client_secret as specified in the doc of `How to Use the REST API`_.
+- The JWT must be created with a Staff user to use all the endpoints this plugin needs.
+- We use the LMS APIs to do the basic functionalities.
+    - To obtain info about enrollments, we use ``GET /enrollment/v1/enrollments/``
+    - To create enrollments, ``POST /enrollment/v1/enrollment``
+    - To perform an unenroll, we use the same endpoint to create enrollment, but we set the attribute is_active in ``False``.
+    - We can pass the flag force in the request to allow you to enroll; disregard the course's enrollment end dates.
+    - To know if a user exists in the platform, ``GET /user/v1/accounts``
+    - If the user does not exist yet, we can get, create, or delete an enrollment allowed with: ``GET, POST, DELETE /api/enrollment/v1/enrollment_allowed/``
+
+
+Consequences
+************
+
+- You need to create an OAuth Application in your platform with a Staff user to use this plugin.
+- The backward compatibility depends on the JWT support in previous Open edx versions.
+- We can use the course enrollment allowed API since Quince.
+- The actions of this plugin are restricted by the endpoints mentioned above. For example, we cannot enroll someone in a course that is in invite-only mode.
+
+
+Rejected Alternatives
+*********************
+
+- Create another plugin to add the needed endpoints: we could use the existing `LMS APIs`_, and we added the course enrollment-allowed API to the edx-platform and brought email support in some of the endpoints.
+
+
+References
+**********
+
+- `Purpose of this repo`_.
+- `OEP-42 Authentication`_.
+- `How to Use the REST API`_.
+- `LMS APIs`_.
+
+.. _Purpose of this repo: 0001-purpose-of-this-repo.html
+.. _OEP-42 Authentication: https://docs.openedx.org/projects/openedx-proposals/en/latest/best-practices/oep-0042-bp-authentication.html#oauth2-and-jwts
+.. _How to Use the REST API: https://docs.openedx.org/projects/edx-platform/en/latest/how-tos/use_the_api.html
+.. _LMS APIs: https://docs.openedx.org/projects/edx-platform/en/latest/references/lms_apis.html#lms-apis

docs/source/decisions/0003-fulfillment-and-refund.rst

@@ -0,0 +1,55 @@
+3. Fulfillment and refund
+==========================
+
+Status
+******
+
+Accepted
+
+
+Context
+*******
+
+This plugin was created focusing on workflows that are streamlined:
+
+- A course bought in WooCommerce will have the consequence that the enrollment for that course is made in the Open edX platform, understood with the enrollment as a seat in a specific course run.
+- If the order is refunded, the associated enrollment will be unenrolled using the soft delete (using the is_active flag) used in regular unenrollments.
+
+
+Decisions
+*********
+- When someone generates a WooCommerce order, which changes the status to 'processing', the plugin generates an enrollment request using the Open edX courses items in the order and the email used in the billing address. The plugin uses the hook ``woocommerce_order_status_changed`` listed in `WooCommerce hooks`_, and it uses 'processing' because that means the payment was completed, and the admin can process/post the items. `WooCommerce payment complete function`_.
+
+    .. image:: /_images/decisions/create-openedx-course-as-product.png
+        :alt: Product data section in a WooCommerce Product
+
+Screenshot of a product data section in a WooCommerce Product.
+
+- When a WordPress admin refunds an Open edX Course in a WooCommerce Order, the plugin creates an enrollment request of type unenroll. The plugin uses the hook ``woocommerce_order_refunded``, also listed in `WooCommerce hooks`_, and it uses the billing email and the Open edX courses marked as refund items in the refund process.
+
+    .. image:: /_images/decisions/refund-order.png
+        :alt: Refund process marking the course to be refunded
+
+Screenshot of a refund process marking the course to be refunded.
+
+
+Consequences
+************
+- We should not set our Open edX Courses as Downloadable WooCommerce Products because if that happened and someone only bought downloadable products, the order never passed through the 'processing' status. The plugin would not create the enrollment request.
+- Refunding is a manual process; a customer cannot do it alone.
+- It is our responsibility to avoid enrollment errors by setting our product as an Open edX course and setting a correct ``course_id`` and ``course_mode`` to the enrollment trigger by an order will be performed well.
+
+
+Rejected Alternatives
+*********************
+
+- Make the hooks that trigger the request variables: to keep the plugin simple.
+
+References
+**********
+
+- `WooCommerce hooks`_.
+- `WooCommerce payment complete function`_.
+
+.. _WooCommerce hooks: https://woocommerce.github.io/code-reference/hooks/hooks.html
+.. _WooCommerce payment complete function: https://github.com/woocommerce/woocommerce/blob/abc476a005b405068b07bd4c50d1797c3dcc396d/plugins/woocommerce/includes/class-wc-order.php#L122

docs/source/decisions/index.rst

@@ -2,7 +2,9 @@ Decisions
 ==========
 
 .. toctree::
-   :maxdepth: 1
+   :titlesonly:
    :caption: Contents:
 
    0001-purpose-of-this-repo
+   0002-api-connection
+   0003-fulfillment-and-refund

docs/source/how-tos/index.rst

@@ -2,7 +2,7 @@ How-tos
 ========
 
 .. toctree::
-   :maxdepth: 1
+   :titlesonly:
    :caption: Contents:
 
    create_an_openedx_app

docs/source/index.rst

@@ -13,6 +13,8 @@ User Guide
 -----------
 
 .. toctree::
+    :titlesonly:
+
     plugin_quickstart
     decisions/index
     how-tos/index
@@ -21,10 +23,9 @@ User Guide
 Open edX Compatibility
 -----------------------
 
-- Palm or latest
 - Tested from Olive
 
-**NOTE:** Enrollment of users who are not platform users is only supported for versions after Palm.
+**NOTE:** Enrollment of users who are not platform users is only supported for versions after Quince.
 
 
 Releases