docs: add naming suggestions to use when creating new filters

openedx · Feb 14, 2025 · d3c18bc · d3c18bc
1 parent ccf780f
commit d3c18bc
Show file tree

Hide file tree

Showing 3 changed files with 12 additions and 0 deletions.
diff --git a/docs/how-tos/create-a-new-filter.rst b/docs/how-tos/create-a-new-filter.rst
@@ -136,6 +136,7 @@ In our example, the filter definition could be implemented as follows:
             )
             return data.get("user"), data.get("course_key"), data.get("mode")
 
+- The ``CourseEnrollmentStarted`` class is the filter definition that inherits from the ``OpenEdxPublicFilter`` class. The name of the class is referred as the filter name and should be descriptive of the filter's purpose. See :doc:`../reference/naming-suggestions` for more information.
 - The ``filter_type`` attribute should be set to the filter type that was identified in the previous steps. This attribute is used to identify the filter in the :term:`filter configuration`.
 - The ``PreventEnrollment`` class is a custom exception that is raised when the filter should halt the application behavior.
 - The ``run_filter`` method is the main method of the filter that is called when the filter is triggered. The method should call the ``run_pipeline`` method, passing down the input arguments and returning the final output of the filter.

diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -13,3 +13,4 @@ References
    real-life-use-cases
    architecture-subdomains
    documenting-filters-classes
+   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 Filters
+#######################################
+
+When naming a new filter and contributing back to this repository, consider the following suggestions:
+
+- Use a name that is descriptive of the filter's purpose. For example, the filter associated with the course enrollment process is named ``CourseEnrollmentStarted`` because it is triggered when a course enrollment starts.
+- Use a name that is unique within the framework.
+- Match the name of the filter to its ``filter_type``. For example, if the ``filter_type`` is a ``org.openedx.learning.course.enrollment.started.v1`` filter, the name of the filter should be ``CourseEnrollmentStarted``. You can use the ``filter_type`` to determine the name of the filter. See :doc:`../decisions/0004-filters-naming-and-versioning` for more information.
+- Avoid using ``Filter`` in the name of the filter. It is implied that the class is a filter, so there is no need to include it in the name.
+- Try reviewing the names of :doc:`existing filters <../reference/filters>` to get an idea of how to name your filter.