From 20ecb70de97f57763d7a1780518b87fee9934776 Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Wed, 5 Apr 2023 14:08:44 -0400 Subject: [PATCH] docs: add open edx event guide (#80) Add guide for new contributors to the Open edX Events library following new standards for Sphinx documentation. --- docs/concepts/hooks-extension-framework.rst | 45 ++++++ docs/concepts/index.rst | 6 + docs/decisions/0001-purpose-of-this-repo.rst | 2 +- .../0002-events-naming-and-versioning.rst | 4 +- docs/decisions/0003-events-payload.rst | 6 +- docs/decisions/index.rst | 4 +- docs/how-tos/adding-events-to-a-service.rst | 39 +++++ docs/how-tos/adding-events-to-event-bus.rst | 14 ++ docs/how-tos/creating-new-events.rst | 146 ++++++++++++++++++ docs/how-tos/index.rst | 9 ++ docs/how-tos/using-events.rst | 116 ++++++++++++++ docs/index.rst | 2 +- docs/quickstarts/index.rst | 6 + .../use-events-to-call-webhook.rst | 121 +++++++++++++++ docs/reference/architecture-subdomains.rst | 17 ++ docs/reference/index.rst | 7 + docs/reference/oeps.rst | 12 ++ 17 files changed, 547 insertions(+), 9 deletions(-) create mode 100644 docs/concepts/hooks-extension-framework.rst create mode 100644 docs/how-tos/adding-events-to-a-service.rst create mode 100644 docs/how-tos/adding-events-to-event-bus.rst create mode 100644 docs/how-tos/creating-new-events.rst create mode 100644 docs/how-tos/using-events.rst create mode 100644 docs/quickstarts/use-events-to-call-webhook.rst create mode 100644 docs/reference/architecture-subdomains.rst create mode 100644 docs/reference/oeps.rst diff --git a/docs/concepts/hooks-extension-framework.rst b/docs/concepts/hooks-extension-framework.rst new file mode 100644 index 00000000..1ad61964 --- /dev/null +++ b/docs/concepts/hooks-extension-framework.rst @@ -0,0 +1,45 @@ +Openedx Hooks Extension Framework +================================= + +To sustain the growth of the Open edX ecosystem, the business rules of the +platform must be open for extension following the open-closed principle. This +framework allows developers to do just that without needing to fork and modify +the main Open edX platform. + +Context +------- + +Hooks are predefined places in the Open edX project core where externally defined +functions can take place. In some cases, those functions can alter what the user +sees or experiences in the platform. Other cases are informative only. All cases +are meant to be extended using Open edX plugins and configuration. + +Hooks can be of two types, events and filters. Events are in essence signals, in +that they are sent in specific application places and whose listeners can extend +functionality. functionality. On the other hand Filters can be used to act on data before +it is put back in the original application flow. In order to allow +extension developers to use the Events and Filters definitions on their plugins, +both kinds of hooks are defined in lightweight external libraries. + +* `openedx-filters`_ +* `openedx-events`_ + +Hooks are designed with stability in mind. The main goal is that developers can +use them to change the functionality of the platform as needed and still be able +to migrate to newer open releases with very little to no development effort. In +the case of the events, this is detailed in the `versioning ADR`_ and the +`payload ADR`_. + +A longer description of the framework and its history can be found in `OEP 50`_. + +.. _OEP 50: https://open-edx-proposals.readthedocs.io/en/latest/oep-0050-hooks-extension-framework.html +.. _versioning ADR: https://github.com/eduNEXT/openedx-events/blob/main/docs/decisions/0002-events-naming-and-versioning.rst +.. _payload ADR: https://github.com/eduNEXT/openedx-events/blob/main/docs/decisions/0003-events-payload.rst +.. _openedx-filters: https://github.com/eduNEXT/openedx-filters +.. _openedx-events: https://github.com/eduNEXT/openedx-events + +On the technical side events are implemented through django signals which makes +them run in the same python process as the service where this library is installed. +Furthermore, events block the running process. Listeners of an event are encouraged +to monitor the performance or use alternative arch patterns such as receiving the +event and defer to launching async tasks than do the slow processing. diff --git a/docs/concepts/index.rst b/docs/concepts/index.rst index 6b799793..cade1612 100644 --- a/docs/concepts/index.rst +++ b/docs/concepts/index.rst @@ -1,2 +1,8 @@ Concepts ======== + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + hooks-extension-framework diff --git a/docs/decisions/0001-purpose-of-this-repo.rst b/docs/decisions/0001-purpose-of-this-repo.rst index 8eab83c5..8e860207 100644 --- a/docs/decisions/0001-purpose-of-this-repo.rst +++ b/docs/decisions/0001-purpose-of-this-repo.rst @@ -19,7 +19,7 @@ Decision -------- In this repository will reside the signals that define the events used by the -edx-platform repo. The same applies to the necessary tooling used by the Hooks +Open edX project. The same applies to the necessary tooling used by the Hooks Extension Framework to manage the events execution and extra tools. Consequences diff --git a/docs/decisions/0002-events-naming-and-versioning.rst b/docs/decisions/0002-events-naming-and-versioning.rst index 2a3d69a3..48cbcfe1 100644 --- a/docs/decisions/0002-events-naming-and-versioning.rst +++ b/docs/decisions/0002-events-naming-and-versioning.rst @@ -80,8 +80,8 @@ Consequences major versions of this library. Also there will not be a need to make a major release if there is no breaking for consecutive Open edX releases. -2. Open edX core and in particular edx-platform must emit the signals meant for -public consumption as they are written in this library, changes in edx-platform +2. The Open edX platform must emit the signals meant for +public consumption as they are written in this library, changes in the platform that require changes in the public signal will require a backwards compatible addition to this library or an altogether new signal with support for the old signal until deprecated and removed. diff --git a/docs/decisions/0003-events-payload.rst b/docs/decisions/0003-events-payload.rst index f003c9e0..a1546ca0 100644 --- a/docs/decisions/0003-events-payload.rst +++ b/docs/decisions/0003-events-payload.rst @@ -14,7 +14,7 @@ Given their public promise status, event hooks have maintainability as the main design goal. The contracts we are creating here should be stable enough to support the growth of the extensions community. That said, things should be allowed to evolve in a backwards compatible manner. When things inevitable break, -they should break in CI. Which should not require the code of edx-platform to +they should break in CI. Which should not require the code of the Open edX platform to test integrations. @@ -46,7 +46,7 @@ Consequences ------------ 1. Extension developers will be able to test their event listeners without the -need to import any edx-platform code. +need to import any Open edX platform code. 2. Consequence of the versioning ADR together with this one, extension developers will be able to test their code with different versions of the library and thus @@ -55,5 +55,5 @@ guarantee that their code will not break when upgrading open releases. 3. The events library will have a dependency on the OpaqueKeys library. 4. Events defined by this library will not be drop-in replacement of current -edx-platform signals. This means some refactoring will be needed when converting +Open edX platform signals. This means some refactoring will be needed when converting the platform code over to openedx_events. diff --git a/docs/decisions/index.rst b/docs/decisions/index.rst index a052b89a..ecff959b 100644 --- a/docs/decisions/index.rst +++ b/docs/decisions/index.rst @@ -1,5 +1,5 @@ -Decisions -========= +Architectural Decision Records (ADRs) +##################################### .. toctree:: :maxdepth: 1 diff --git a/docs/how-tos/adding-events-to-a-service.rst b/docs/how-tos/adding-events-to-a-service.rst new file mode 100644 index 00000000..532284c7 --- /dev/null +++ b/docs/how-tos/adding-events-to-a-service.rst @@ -0,0 +1,39 @@ +How to add an Open edX Event to a service +========================================= + +The next step after creating your first event in the Open edX Events library is to trigger the event in the service +you implemented it for. Here is a checklist of what we've done so far when including a new event to a service: + +- Add the openedx-events library to the service project. +- Import the events' data and definition into the place where the event be triggered. Remember the event's purpose when + choosing a place to send the new event. +- Add inline documentation with the ``event_implemented_name``. This matches the ``event_name`` in line documentation from the library. +- Refer to the service project's contribution guidelines and follow the instructions. Then, open a new pull request! + +Consider the addition of the event ``STUDENT_REGISTRATION_COMPLETED`` to edx-platform as an example: + +.. code-block:: python + + # Location openedx/core/djangoapps/user_authn/views/register.py + # .. event_implemented_name: COURSE_ENROLLMENT_CREATED + COURSE_ENROLLMENT_CREATED.send_event( + enrollment=CourseEnrollmentData( + user=UserData( + pii=UserPersonalData( + username=user.username, + email=user.email, + name=user.profile.name, + ), + id=user.id, + is_active=user.is_active, + ), + course=course_data, + mode=enrollment.mode, + is_active=enrollment.is_active, + creation_date=enrollment.created, + ) + ) + +If you want to know more about how the integration of the first events' batch went, check out the `PR 28266`_. + +.. _PR 28266: https://github.com/openedx/edx-platform/pull/28266 diff --git a/docs/how-tos/adding-events-to-event-bus.rst b/docs/how-tos/adding-events-to-event-bus.rst new file mode 100644 index 00000000..e5b64d0a --- /dev/null +++ b/docs/how-tos/adding-events-to-event-bus.rst @@ -0,0 +1,14 @@ +Using the Open edX Event bus +============================ + +After creating a new Open edX Event, you might need to send it across services +instead of just within the same process. For this kind of use-cases, you might want +to use the Open edX Event Bus. Here, we list useful information about +adding a new event to the event bus: + +- `How to start using the Event Bus`_ +- `Sample pull request adding new Open edX Events to the Event Bus` + + +.. _How to start using the Event Bus: https://openedx.atlassian.net/wiki/spaces/AC/pages/3508699151/How+to+start+using+the+Event+Bus +.. _Sample pull request adding new Open edX Events to the Event Bus: https://github.com/openedx/edx-platform/pull/31350 diff --git a/docs/how-tos/creating-new-events.rst b/docs/how-tos/creating-new-events.rst new file mode 100644 index 00000000..4bf7e2da --- /dev/null +++ b/docs/how-tos/creating-new-events.rst @@ -0,0 +1,146 @@ +How to create a new Open edX Event +================================== + +The mechanisms implemented by the Open edX Events library are supported and maintained by the Open edX community. +Therefore, we've put together a guide on how to add a new event to the library so future contributions are effective. + + +1. Propose the new event to the community +----------------------------------------- + +When creating a new event, you must justify its implementation. For example, you could create a post in Discuss, +send a message through slack or open a new issue in the library repository listing your use cases for it. Or even, +if you have time, you could accompany your proposal with the implementation of the event to illustrate its behavior. + +.. note:: + There is an open discussion about whether organization scoped events would also exist in openedx-events, + in which case this step would be optional. See issue `Organization scoped events `_. + +2. Place your event in an architecture subdomain +------------------------------------------------- + +As specified in the Architectural Decisions Record (ADR) events naming and versioning, the event definition needs an Open edX Architecture +Subdomain for: + +- The name of the event: ``{Reverse DNS}.{Architecture Subdomain}.{Subject}.{Action}.{Major Version}`` +- The package name where the definition will live, eg. ``learning/`` or ``content_authoring/``. + +For those reasons, after studying your new event purpose, you must place it in one of the subdomains already in use, or introduce a new subdomain: + ++-------------------+----------------------------------------------------------------------------------------------------+ +| Subdomain name | Description | ++===================+====================================================================================================+ +| Content Authoring | Allows educators to create, modify, package, annotate (tag), and share learning content. | ++-------------------+----------------------------------------------------------------------------------------------------+ +| Learning | Allows learners to consume content and perform actions in a learning activity on the platform. | ++-------------------+----------------------------------------------------------------------------------------------------+ + +New subdomains may require some discussion, because there does not yet exist and agreed upon set on subdomains. So we encourage you to start the conversation +as soon as possible through any of the communication channels available. + +Refer to `edX DDD Bounded Contexts `_ confluence page for more documentation on domain-driven design in the Open edX project. + +3. Create the data attributes for the event (OEP-49) +---------------------------------------------------- + +Events send `data attributes `_ when triggered. Therefore, when designing your new event definition you must +decide if an existent data class works for your use case or you must create a new one. If the answer is the latter, then try to answer: + +- Which attributes of the object are the most relevant? +- Which type are they? +- Are any of them optional/required? + +And with that information, create the new class justifying each decision. The class created in this step must comply +with: + +- It should be created in the `data.py` file, as described in the OEP-49, in the corresponding architectural subdomain. Refer to Naming Conventions ADR for more + on events subdomains. +- It should follow the naming conventions used across the other events definitions. + +Consider the user data representation as an example: + +.. code-block:: python + + @attr.s(frozen=True) + class CourseData: + """ + Attributes defined for Open edX Course Overview object. + + Arguments: + course_key (str): identifier of the Course object. + display_name (str): display name associated with the course. + start (datetime): start date for the course. + end (datetime): end date for the course. + """ + + course_key = attr.ib(type=CourseKey) + display_name = attr.ib(type=str, factory=str) + start = attr.ib(type=datetime, default=None) + end = attr.ib(type=datetime, default=None) + + + @attr.s(frozen=True) + class CourseEnrollmentData: + """ + Attributes defined for Open edX Course Enrollment object. + + Arguments: + user (UserData): user associated with the Course Enrollment. + course (CourseData): course where the user is enrolled in. + mode (str): course mode associated with the course. + is_active (bool): whether the enrollment is active. + creation_date (datetime): creation date of the enrollment. + created_by (UserData): if available, who created the enrollment. + """ + + user = attr.ib(type=UserData) + course = attr.ib(type=CourseData) + mode = attr.ib(type=str) + is_active = attr.ib(type=bool) + creation_date = attr.ib(type=datetime) + created_by = attr.ib(type=UserData, default=None) + +4. Create the event definition +------------------------------ + +Open edX Events are instances of the class OpenEdxPublicSignal, this instance represents the event definition that +specifies: + +- The event type which should follow the conventions in the Naming Conventions ADR. +- The events' payload, here you must use the class you decided on before. + +The definition created in this step must comply with: + +- It should be created in the `signals.py` file in the corresponding subdomain. Refer to Naming Conventions ADR for more + on events subdomains. +- It should follow the naming conventions specified in Naming Conventions ADR. +- It must be documented using in-line documentation with at least: `event_type`, `event_name`, `event_description` and + `event_data`: + ++-------------------+----------------------------------------------------------------------------------------------------+ +| Annotation | Description | ++===================+====================================================================================================+ +| event_type | Identifier across services of the event. Should follow the events naming conventions. | ++-------------------+----------------------------------------------------------------------------------------------------+ +| event_name | Name of the variable storing the event instance. | ++-------------------+----------------------------------------------------------------------------------------------------+ +| event_description | General description which includes when the event should be emitted. | ++-------------------+----------------------------------------------------------------------------------------------------+ +| event_data | What type of class attribute the event sends. | ++-------------------+----------------------------------------------------------------------------------------------------+ + +Consider the following example: + +.. code-block:: python + + # Location openedx_events/learning/signals.py + # .. event_type: org.openedx.learning.course.enrollment.created.v1 + # .. event_name: COURSE_ENROLLMENT_CREATED + # .. event_description: emitted when the user's enrollment process is completed. + # .. event_data: CourseEnrollmentData + COURSE_ENROLLMENT_CREATED = OpenEdxPublicSignal( + event_type="org.openedx.learning.course.enrollment.created.v1", + data={ + "enrollment": CourseEnrollmentData, + } + ) diff --git a/docs/how-tos/index.rst b/docs/how-tos/index.rst index 5147f808..f8908b33 100644 --- a/docs/how-tos/index.rst +++ b/docs/how-tos/index.rst @@ -1,2 +1,11 @@ How-tos ####### + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + creating-new-events + adding-events-to-a-service + adding-events-to-event-bus + using-events diff --git a/docs/how-tos/using-events.rst b/docs/how-tos/using-events.rst new file mode 100644 index 00000000..a7acc628 --- /dev/null +++ b/docs/how-tos/using-events.rst @@ -0,0 +1,116 @@ +Using Open edX Events +===================== + +How to use +---------- + +Using openedx-events in your code is very straight forward. We can consider the +two possible cases, sending or receiving an event. + +Receiving events +^^^^^^^^^^^^^^^^ + +This is one of the most common use cases for plugins. The Open edX platform will send +an event and you want to react to it in your plugin. + +For this you need to: + +1. Include openedx-events in your dependencies. +2. Connect your receiver functions to the signals being sent. + +Connecting signals can be done using regular django syntax: + +.. code-block:: python + + from openedx_events.learning.signals import STUDENT_REGISTRATION_COMPLETED + + @receiver(STUDENT_REGISTRATION_COMPLETED) + def your_receiver_function(**kwargs): + # your implementation here + + +Or at the apps.py + +.. code-block:: python + + { + "signals_config": { + "lms.djangoapp": { + "relative_path": "your_module_name", + "receivers": [ + { + "receiver_func_name": "your_receiver_function", + "signal_path": "openedx_events.learning.signals.STUDENT_REGISTRATION_COMPLETED", + }, + ], + } + } + } + + +In case you are listening to an event in an Open edX platform repo, you can directly +use the django syntax since the apps.py method will not be available without the +plugin system. + +.. warning:: + For non-trivial work, we encourage using asynchronous tasks in your receiver functions in order + to avoid affecting the performance of the service. + +Sending events +^^^^^^^^^^^^^^ + +Sending events requires you to import both the event definition as well as the +attr data classes that encapsulate the event data. + +.. code-block:: python + + from openedx_events.learning.data import UserData, UserPersonalData + from openedx_events.learning.signals import STUDENT_REGISTRATION_COMPLETED + + STUDENT_REGISTRATION_COMPLETED.send_event( + user=UserData( + pii=UserPersonalData( + username=user.username, + email=user.email, + name=user.profile.name, + ), + id=user.id, + is_active=user.is_active, + ), + ) + +You can do this both from the Open edX platform code as well as from an openedx +plugin. + +Testing events +^^^^^^^^^^^^^^ + +Testing your code in CI, specially for plugins is now possible without having to +import the complete Open edX platform as a dependency. + +To test your functions you need to include the openedx-events library in your +testing dependencies and make the signal connection in your test case. + +.. code-block:: python + + from openedx_events.learning.signals import STUDENT_REGISTRATION_COMPLETED + + def test_your_receiver(self): + STUDENT_REGISTRATION_COMPLETED.connect(your_function) + STUDENT_REGISTRATION_COMPLETED.send_event( + user=UserData( + pii=UserPersonalData( + username='test_username', + email='test_email@example.com', + name='test_name', + ), + id=1, + is_active=True, + ), + ) + + # run your assertions + +Changes in the openedx-events library that are not compatible with your code +should break this kind of test in CI and let you know you need to upgrade your +code. diff --git a/docs/index.rst b/docs/index.rst index 23a6c175..59877fa7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,7 +4,7 @@ contain the root `toctree` directive. Welcome to Open edX Events' documentation! -=========================================== +============================================ .. toctree:: :maxdepth: 2 diff --git a/docs/quickstarts/index.rst b/docs/quickstarts/index.rst index a60e9164..16cd167c 100644 --- a/docs/quickstarts/index.rst +++ b/docs/quickstarts/index.rst @@ -1,2 +1,8 @@ Quickstarts ########### + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + use-events-to-call-webhook diff --git a/docs/quickstarts/use-events-to-call-webhook.rst b/docs/quickstarts/use-events-to-call-webhook.rst new file mode 100644 index 00000000..3d8b4d86 --- /dev/null +++ b/docs/quickstarts/use-events-to-call-webhook.rst @@ -0,0 +1,121 @@ +Using Open edX Events in the LMS service +======================================== + +Live example +------------ + +For a complete and detailed example you can see the `openedx-events-2-zapier`_ +plugin. This is a fully functional plugin that connects to +``STUDENT_REGISTRATION_COMPLETED`` and ``COURSE_ENROLLMENT_CREATED`` and sends +the relevant information to zapier.com using a webhook. + +Let's see it working! + +Setup your environment +---------------------- + +This tutorial assumes you're using `Tutor`_ > 13.x and its default services are +already provisioned. + +Installation +------------ + +For this tutorial to work, you'll need a openedx image with the following package +installed: + +- `openedx-events-2-zapier`_ + +You can use your preferred method for installing new packages in Tutor. + +Configuration +------------- + +The package we just installed is a `Django plugin`_, which adds additional +configurations to our working environment thanks to the extension mechanisms put in place. Now, +signal receivers are listening to the registration and enrollment events sent within the LMS service. + +The following is the implementation for the signal receiver listening for the event ``STUDENT_REGISTRATION_COMPLETED``: + +.. code-block:: python + + # File openedx_events_2_zapier/receivers.py + class OpenedxEventsSamplesConfig(AppConfig): + """ + Configuration for the openedx_events_2_zapier Django application. + """ + + name = "openedx_events_2_zapier" + + plugin_app = { + "settings_config": {}, + "signals_config": { + "lms.djangoapp": { + "relative_path": "receivers", + "receivers": [ + { + "receiver_func_name": "send_user_data_to_webhook", + "signal_path": "openedx_events.learning.signals.STUDENT_REGISTRATION_COMPLETED", + }, + ], + } + }, + } + + # File openedx_events_2_zapier/receivers.py + def send_user_data_to_webhook(user, **kwargs): + """ + POST user's data after STUDENT_REGISTRATION_COMPLETED event is sent. + + The data sent to the webhook is, for example: + + 'user_id': 39, + 'user_is_active': True, + 'user_pii_username': 'test', + 'user_pii_email': 'test@example.com', + 'user_pii_name': 'test', + 'event_metadata_id': UUID('b1be2fac-1af1-11ec-bdf4-0242ac12000b'), + 'event_metadata_event_type': 'org.openedx.learning.student.registration.completed.v1', + 'event_metadata_minorversion': 0, + 'event_metadata_source': 'openedx/lms/web', + 'event_metadata_sourcehost': 'lms.devstack.edx', + 'event_metadata_time': datetime.datetime(2021, 9, 21, 15, 36, 31, 311506), + 'event_metadata_sourcelib': [0, 6, 0] + + This format is convenient for Zapier to read. + """ + user_info = asdict(user) + event_metadata = asdict(kwargs.get("metadata")) + zapier_payload = { + "user": user_info, + "event_metadata": event_metadata, + } + # WARNING: The receiver function implemented in this tutorial was intended to be lightweight, just to + # serve as an example for events' receivers. However, in production, you must use asynchronous tasks + # to avoid creating bottlenecks if you wish for others to use your implementation. + requests.post( + settings.ZAPIER_REGISTRATION_WEBHOOK, + flatten_dict(zapier_payload), + ) + +Those receivers work out of the box after the plugin installation. Now, we must +set the plugin settings which indicate where to send the events data. For this, +go to ``env/apps/openedx/settings/development.py`` and add your Zapier configuration: + +.. code-block:: python + + ZAPIER_REGISTRATION_WEBHOOK = "https://hooks.zapier.com/hooks/catch///" + ZAPIER_ENROLLMENT_WEBHOOK = "https://hooks.zapier.com/hooks/catch///" + +Getting data from Zapier +------------------------ + +Now that you have configured both receivers, you'll need to trigger the events +so you receive the events data in Zapier. Try it out! + +.. _openedx-events-2-zapier: https://github.com/eduNEXT/openedx-events-2-zapier +.. _Tutor: https://github.com/overhangio/tutor +.. _Django plugin: https://github.com/openedx/edx-django-utils/blob/master/edx_django_utils/plugins/README.rst + +.. warning:: + The receiver function implemented in this tutorial was intended to be lightweight, just to serve as an example for events' receivers. However, in production + settings, we encourage the use of asynchronous tasks to avoid creating bottlenecks. diff --git a/docs/reference/architecture-subdomains.rst b/docs/reference/architecture-subdomains.rst new file mode 100644 index 00000000..b69adbc6 --- /dev/null +++ b/docs/reference/architecture-subdomains.rst @@ -0,0 +1,17 @@ +Architecture Subdomains +======================= + +Here we list useful information about Open edX architecture subdomains and +their use in the Hooks Extension framework: + +- `Events Naming and Versioning`_ +- `Notes on events design and subdomains`_ +- `edX Domain Driven Design documentation`_ +- `Subdomains from OEP-41`_ +- `Message Content Data Guidelines`_ + +.. _Events Naming and Versioning: https://github.com/openedx/openedx-events/blob/main/docs/decisions/0002-events-naming-and-versioning.rst#L1 +.. _edX Domain Driven Design documentation: https://openedx.atlassian.net/wiki/spaces/AC/pages/213910332/Domain-Driven+Design +.. _`Subdomains from OEP-41`: https://docs.openedx.org/projects/openedx-proposals/en/latest/architectural-decisions/oep-0041-arch-async-server-event-messaging.html#subdomain-from-domain-driven-design +.. _`Message Content Data Guidelines`: https://docs.openedx.org/projects/openedx-proposals/en/latest/architectural-decisions/oep-0041-arch-async-server-event-messaging.html?highlight=subdomain#message-content-data-guidelines +.. _`Notes on events design and subdomains`: https://github.com/openedx/openedx-events/issues/72#issuecomment-1179291340 diff --git a/docs/reference/index.rst b/docs/reference/index.rst index ba5ea57c..28c276cc 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -1,2 +1,9 @@ References ########## + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + oeps + architecture-subdomains diff --git a/docs/reference/oeps.rst b/docs/reference/oeps.rst new file mode 100644 index 00000000..519b5833 --- /dev/null +++ b/docs/reference/oeps.rst @@ -0,0 +1,12 @@ +Open edX Proposals +================== + +Here we list the Open edX proposals used throughout the project, that will help +you understand the major decisions made during the library's design. + +- The `Hooks extension framework (OEP-50)`_ which specifies its motivation, implementation details, rationale, performance considerations, general use cases and more. The goal of the OEP-50 is give the extensions' developer a glance on the framework implementation and design. + +- The `Asynchronous Server Event Message Format (OEP-41)`_, which specifies the header information format sent by the events. For a detailed description on the impact of the OEP-41, please refer to the Events Payload ADR. + +.. _Hooks extension framework (OEP-50): https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0050-hooks-extension-framework.html +.. _Asynchronous Server Event Message Format (OEP-41): https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0041-arch-async-server-event-messaging.html