Merge pull request #86 from edx/schen/update_doc

Schen/update doc

CHANGELOG.rst

@@ -13,6 +13,8 @@ Change Log
 
 Unreleased
 ~~~~~~~~~~
+* Updated internal documentation. Added to the readme and a new docs context
+
 [2.3.2] - 2022-03-11
 ~~~~~~~~~~~~~~~~~~~~
 * Add simple_history tracking to the VerifiedName model

README.rst

@@ -1,19 +1,129 @@
+####################
 edx-name-affirmation
+####################
+
+| |Build Status| |Coveralls|
+
+This library contains data model and business logic to store verified 
+personal information for learners of the edx-platform.
+This library is designed to be a pluggable library to the edx-platform.
+
+Overview
+========
+
+This library mainly stores various stages of a learner's verified identifying information.
+The prevalent example is the learner's full name. To verify the full name, the learner
+has to first initiate from UI that is part of the platform.
+Here are the steps of which the PII information, for example: full name, goes through:
+
+1. learner requests to update the name
+2. learner is brought to go through ID verification process
+3. learner submit the ID verification after providing supporting evidence
+4. the ID Verification reviewer approves or denies the verification
+5. the library receives the verdict and updates the name record in the model accordingly
+
+The above process can also be triggered by a Proctored exam attempt, where the exam attempt status
+can be the input into this library to create and update the name record's status. In this case,
+the learner do not have to go through ID Verification. The proctoring process always collects ID
+verification evidence.
+
+For more context of the library, see `context`_.
+
+Dependencies
+------------
+
+In addition to the edx-platform repository this library is installing into, the library also leverages
+the `frontend-app-account`_ Micro-Frontend to capture learners' attempt to update their full name.
+
+Installing in Docker Devstack
+-----------------------------
+
+Assuming that your ``devstack`` repo lives at ``~/edx/devstack``
+and that ``edx-platform`` lives right alongside that directory, you'll want
+to checkout ``edx-name-affirmation`` and have it live in ``~/edx/src/edx-name-affirmation``.
+This will make it so that you can access it inside an LMS container shell
+and easily make modifications for local testing.
+
+Run ``make lms-shell`` from your ``devstack`` directory to enter a running LMS container.
+Once in there, you can do the following to have your devstack pointing at a local development
+version of ``edx-name-affirmation``:
+
+.. code:: bash
+
+    $ pushd /edx/src/edx-name-affirmation
+    $ virtualenv venv/
+    $ source venv/bin/activate
+    $ make install
+    $ make test  # optional, if you want to see that everything works
+    $ deactivate
+    $ pushd  # should take you back to /edx/edx-platform
+    $ pip uninstall -y edx_name_affirmation
+    $ pip install -e /edx/src/edx-name-affirmation
+
+Alternatively, you can add ``./src/edx-name-affirmation`` to the edx-platform ``private.txt`` of the ``requirements`` folder
+This way, when you are pip installing within edx-platform, you don't have to perform the above step again.
+
+Enabling in LMS
+---------------
+Make sure your LMS settings have the Feature ``ENABLE_SPECIAL_EXAMS`` enabled.
+Check your edx-platform ``lms/env`` settings file.
+
+Disable the plugin library
+--------------------------
+
+There are two ways to disable the plugin library:
+
+- You can uninstall the library from edx-platform.
+- In the `setup.py`_, you can remove the ``entry_points`` into either ``LMS`` or ``CMS``
+
+Development
+-----------
+
+installation and settings
+=========================
+
+Install to the python virtualenv with help from virtualenvwrapper:
+
+.. code:: bash
+
+    $ pip install --user virtualenvwrapper
+    $ mkvirtualenv nameaffirmation
+
+For detailed instructions on virtualenvwrapper: https://virtualenvwrapper.readthedocs.io/en/latest/install.html
+
+Running tests
+=============
+
+From the edx-name-affirmation repo root, run the tests with the following command:
+
+.. code:: bash
+
+    $ make test
+
+Running code quality check
+==========================
+
+From the edx-name-affirmation repo root, run the quality checks with the following command:
+
+.. code:: bash
+
+    $ make quality
+
+
+Package Requirements
 ====================
 
-.. image:: https://img.shields.io/github/license/edx/django-component-views.svg
-    :target: https://github.com/edx/edx-name-affirmation/blob/master/LICENSE.txt
-    :alt: License
+``requirements/dev.txt`` contains a list of package dependencies which are required for this package.
+
+``requirements/test.txt`` is used to install the same dependencies when running the tests for this package.
 
-This package contains name affirmation logic in order to help ensure academic integrity for edx-platform.
 
 License
 -------
 
 The code in this repository is licensed under the AGPL 3.0 unless
 otherwise noted.
 
-Please see ``LICENSE.txt`` for details.
 
 How To Contribute
 -----------------
@@ -37,4 +147,13 @@ Have a question about this repository, or about Open edX in general?  Please
 refer to this `list of resources`_ if you need any assistance.
 
 .. _list of resources: https://open.edx.org/getting-help
+.. _context: ./docs/context.rst
+.. _frontend-app-account: https://github.com/openedx/frontend-app-account
+.. _setup.py: ./setup.py
+
+
+.. |Build Status| image:: https://github.com/edx/edx-name-affirmation/workflows/Python%20CI/badge.svg?branch=main
+  :target: https://github.com/edx/edx-name-affirmation/actions?query=workflow%3A%22Python+CI%22
 
+.. |Coveralls| image:: https://coveralls.io/repos/edx/edx-name-affirmation/badge.svg?branch=main&service=github
+  :target: https://coveralls.io/github/edx/edx-name-affirmation?branch=main

docs/context.rst

@@ -0,0 +1,46 @@
+###########
+The Context
+###########
+
+Why
+===
+
+Problem
+-------
+
+Around the beginning of calendar year 2021, it was recognized within edX that the ID Verification process we
+force the learner through, was not aligning with the mission of wider educational access. edX wants to trusting
+the learner and assuming good intent. We wanted to reduce the barrier to entry for being a paying leaner on edX.
+We should only require ID Verification on a minimal set of learners that want to change the name on their certificates.
+Specific examples of ID verification challenges were (in no particular order):
+
+- ID Verification vendors do not support a wide range of languages. Asian students had a hard time getting verified
+- ID Verification process has a greater than 20% denial rate. This introduced a lot of support issues and learners pain
+- Before proctoring exams, we would require ID Verification. This means learners has to provide PII evidence
+  twice before exams. Furthermore, learners who has trouble with ID Verification process sometimes lost the chance to take the exams
+- edX collecting learners verification documents is at security risk of hacking and leaking.
+- The cost of ID verification process on edX is trending higher as the number of active paying learners grow
+
+
+Solution
+--------
+
+It was proposed by edX product management that we should create a newer and more lightweight process to replace
+ID Verification process for all paying learners. The design was to ask learner to go through honor code signature.
+The honor code is captured by the django app agreements_.
+In addition to the honor code signature, if the learners who fits the following criteria, we would trigger ID Verification:
+
+- Has a downloadable course certificate
+- The learner changes more than 1 character in their profile name,
+  or they have already changed their profile name 3 times 
+
+Furthermore, if the learner is going through Proctoring exams, the full name provided and verified as part of
+the proctoring process, will be saved as a verified name in this library.
+
+Timeline
+--------
+The solution was designed summer of 2021 and implemented in fall and winter of 2022. On Jan 19th, 2022, learners on
+edx.org was no longer required to go through ID verification to get their certificates.
+
+
+.. _agreements: https://github.com/openedx/edx-platform/tree/8070dd9be000da3fac86be19b5f0274f3d073630/openedx/core/djangoapps/agreements