docs: Open edX events naming

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.

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.