docs: add naming suggestions to use when creating new events

openedx · Feb 14, 2025 · 569eb3f · 569eb3f
1 parent acd824c
commit 569eb3f
Show file tree

Hide file tree

Showing 3 changed files with 12 additions and 1 deletion.
diff --git 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
@@ -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
@@ -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/naming-suggestions>` in the repository to ensure that the name you choose is unique and follows the naming conventions.