diff --git a/docs/decisions/0002-events-naming-and-versioning.rst b/docs/decisions/0002-events-naming-and-versioning.rst new file mode 100644 index 00000000..2a3d69a3 --- /dev/null +++ b/docs/decisions/0002-events-naming-and-versioning.rst @@ -0,0 +1,99 @@ +2. Open edX events naming and versioning +======================================== + +Status +------ + +Accepted + + +Context +------- + +Event type hooks are an important public promise. They are a strong foundation +of a healthy ecosystem of extensions for the Open edX world and have been +recognized as such by the arch team of the Open edX core and also by the community. + +This ADR has the purpose of defining the rules to be followed when naming an +Open edX Event with the intent of covering the use cases of: + +* Open edX core developers wanting to add new events. +* Open edX core developers wanting to deprecate and eventually remove events. +* Open edX extension developers wanting to create and maintain stable + applications, even when the events framework evolves and changes over time. +* Service developers wanting to listen for events using message queues. + +The decisions reached in this ADR are the product of open discussions in the ADR +PR history. + + +Decisions +--------- + +1. The name of an event will be a ``string`` that follows the `type format`_ +defined in the `OEP-41`_: + +``{Reverse DNS}.{Architecture Subdomain}.{Subject}.{Action}.{Major Version}`` + +Examples: + +* org.openedx.learning.course.enrollment.created.v1 +* org.openedx.learning.student.registration.completed.v2 +* org.openedx.learning.session.login.completed.v1 + +2. The signal definitions will be placed written in code in the way that is more +practical and familiar for python developer with emphasis on Django experience. +Definition will be grouped by subdomain along with other data structures in a +way that favors reuse. +There will be a subclass of Django signal that accepts the event name and makes +available for listeners of the emitted events and the frameworks other event +processing queues. Only the `Architecture Subdomain`_ part of the event name will +be used in the package name of the signal definition. + +3. The events library will use SemVer 2. The major version will not be tied to +Open edX releases for the time being. We still recognize that Open edX releases +are the logical boundary to remove signals and therefore make breaking changes +such as remove signal definitions. + +4. The Major version of an event will be both part of the `event name` and also +be written to the variable defining the signal. However version 1 (V1) of an +event will remove the _V1 suffix for readability. We also expect to have +relatively few breaking changes to the signal definitions. The minor version of +a signal will be written in the payload as part of the header information +defined in `OEP-41`_. + +5. The events library will be a single library containing the signal definitions, +the simple data structures required and the necessary classes and tools to +support the events framework. The definitions of the signals will be written +with a logical boundary such that if the project ever decides to separate them +in a split library there is no necessary large refactor. + +.. _type format: https://open-edx-proposals.readthedocs.io/en/latest/oep-0041-arch-async-server-event-messaging.html#id5 +.. _Architecture Subdomain: https://openedx.atlassian.net/wiki/spaces/AC/pages/663224968/edX+DDD+Bounded+Contexts +.. _OEP-41: https://open-edx-proposals.readthedocs.io/en/latest/oep-0041-arch-async-server-event-messaging.html#specification + + +Consequences +------------ + +1. There will not be a necessary correspondence between open edX release and +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 +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. + +3. Changing the arguments passed to an event must always be done in a backwards +compatible way since making it incompatible warrants the use of a new major +version. + +4. Since it was decided from the OEP-50 that Django Signals is the underlying +mechanism for messages, service developers wanting to listen for events using +message queues will still require a way to transform the signal-based events +into the message queue technology. This part of the solution is not covered by +this library at this time. In the future we may consider adding it here or setup +a separate library for those events. We leave that decision open for now because +many details about the implementation are still unclear. diff --git a/docs/decisions/0003-events-payload.rst b/docs/decisions/0003-events-payload.rst new file mode 100644 index 00000000..f003c9e0 --- /dev/null +++ b/docs/decisions/0003-events-payload.rst @@ -0,0 +1,59 @@ +3. Open edX events payload conventions +====================================== + +Status +------ + +Accepted + + +Context +------- + +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 +test integrations. + + +Decisions +--------- + +1. Events will receive header information in line with the `OEP-41 format`_. +However all the fields but `data`, which are also referred as the envelope +information, will be wrapped in a dictionary. The data specific to the event +will be passed as unpacked named arguments so that function signature mismatch +errors can be caught in CI. + +2. The envelope information will be calculated on the fly by the +`OpenEdxPublicSignal` class to keep this information out of the way when writing +the event calling location as well. + +3. The data sent to an event will always use the form of attr objects following +the `OEP-49 data pattern`_ . This data objects will be defined in the events +library and will be scoped to the Architecture Subdomain they are in. Data +objects should use only serializable python primitives and standard types with +the exception of OpaqueKeys. + + +.. _OEP-41 format: https://open-edx-proposals.readthedocs.io/en/latest/oep-0041-arch-async-server-event-messaging.html#message-format +.. _OEP-49 data pattern: https://open-edx-proposals.readthedocs.io/en/latest/oep-0049-django-app-patterns.html#id9 + + +Consequences +------------ + +1. Extension developers will be able to test their event listeners without the +need to import any 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 +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 +the platform code over to openedx_events.