diff --git a/docs/how-tos/create-a-new-event.rst b/docs/how-tos/create-a-new-event.rst index 5ac52e2c..11a951de 100644 --- a/docs/how-tos/create-a-new-event.rst +++ b/docs/how-tos/create-a-new-event.rst @@ -186,7 +186,7 @@ The :term:`Event Definition` should be implemented in the corresponding subdomai - The event definition should be documented using in-line documentation with at least ``event_type``, ``event_name``, ``event_description``, and ``event_data``. This will help consumers understand the event and react to it. See :doc:`../reference/in-line-code-annotations-for-an-event` for more information. - The :term:`Event Type` should be unique and follow the naming convention for event types specified in the :doc:`../decisions/0002-events-naming-and-versioning` ADR. This is used by consumers to identify the event. -- The ``event_name`` should be a constant that is used to identify the event in the code. +- The ``event_name`` should be a constant that is used to identify the event in the code. See :doc:`../reference/naming-suggestions` for more information on naming events. - The ``event_description`` should describe what the event is about and why it is triggered. - The ``event_data`` should be the payload class that is used to define the data that is included in the event. - The ``data`` dictionary should contain the payload class that is used to define the data that is included in the event. This will help consumers understand the event and react to it. Try using a descriptive name for the data field, but keep consistency with the payload class name. Avoid using suffixes like ``_data`` or ``_payload`` in the data field name. diff --git a/docs/reference/index.rst b/docs/reference/index.rst index eeaa88ce..9cdaa57a 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -14,3 +14,4 @@ References oeps architecture-subdomains real-life-use-cases + naming-suggestions diff --git a/docs/reference/naming-suggestions.rst b/docs/reference/naming-suggestions.rst new file mode 100644 index 00000000..4c07f036 --- /dev/null +++ b/docs/reference/naming-suggestions.rst @@ -0,0 +1,10 @@ +Naming Suggestions for Open edX Events +######################################## + +When naming a new event and contributing it back to this repository, consider the following suggestions: + +- Use a name that is descriptive to the event's purpose. For example, the event associated with a user's enrollment in a course is named ``COURSE_ENROLLMENT_CREATED``, which clearly indicates the event's purpose. +- Use a name that is unique within the framework. +- Match the name to the ``event_type`` identifier. For example, the ``COURSE_ENROLLMENT_CREATED`` event has an ``event_type`` of ``org.openedx.learning.course.enrollment.created.v1``. You can use the ``event_type`` as a reference when naming the event. See :doc:`../decisions/0002-events-naming-and-versioning` for more information on naming and versioning events. +- Avoid using ``event`` in the name. It is implied that the variable is an event, so there is no need to include it in the name. +- Try reviewing the :doc:`existing events <../reference/events>` in the repository to ensure that the name you choose is unique and follows the naming conventions.