4. Open edX filters naming and versioning#

Status#

Draft

Context#

Filter-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 Filter with the intent of covering the use cases of:

  • Open edX core developers wanting to add new filters.

  • Open edX core developers wanting to deprecate and eventually remove filters.

  • Open edX core developers wanting to add additional information to an existing filters in a mostly backward compatible way.

  • Open edX extension developers wanting to have as few restrictions as reasonable on the extension capabilities at the filter location.

  • Open edX extension developers wanting to create and maintain stable applications, even when the filters framework evolves and changes over time.

Evolving stably and creating few restrictions on the filters are two use cases at odds with each other, and this ADR and overall framework tries to find a good balance between them.

Decisions#

1. The name of a filter will be a string that follows the type format defined in the OEP-41:

{Reverse DNS}.{Architecture Subdomain}.{Subject}.{Action}.{Major Version}

Rationale: Although filters are geared more towards edx-platform and will not be sent via a message bus, we still find that having a consistent naming scheme is very important.

Examples:

  • org.openedx.learning.course.enrollment.creation.requested.v1

  • org.openedx.learning.student.registration.requested.v2

  • org.openedx.learning.session.login.requested.v1

  • org.openedx.learning.certificate.render.started.v1

2. This name will be used as part of the configuration of every filter, for example:

OPEN_EDX_FILTERS_CONFIG = {
    "org.openedx.learning.course.enrollment.creation.requested.v1": {
        "pipeline": [
            "first_plugin.module.check_enrollment_if_enterprise",
            "second_plugin.module.check_crm_data_for_enrollment",
        ],
    }
}

3. The filter definitions will be placed written in code in a way that is more practical and familiar for python developers with an emphasis on Django experience. The definition will be grouped by subdomain along with other data structures in a way that favors reuse. Only the Architecture Subdomain part of the filter name will be used in the package name of the filter definition. What constitutes a filter is that is a class that inherits from the main OpenEdxPublicFilter, which implements all the inner workings of the framework.

4. The filters 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 filters and make breaking changes such as eliminating filter definitions.

5. Each filter will have a major and minor version only. The major version will be part of the filter name and be written to the classname defining the filter. However, version 1 (V1) of a filter will remove the _V1 suffix for readability. We also expect to have relatively few breaking changes to the filter definitions. The minor version of a filter will be written in the payload passed to the implementing function so that extension developers can react to it if they so desire.

6. The filters library will be a single library containing the filter definitions, the necessary classes, and the tools to support the filters framework. These definitions 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.

Consequences#

1. There will not be a necessary correspondence between Open edX releases 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 run the filters meant for public consumption as they are written in this library, changes in edx-platform that require changes in the public filter will require a backward compatible addition to this library or an altogether new filter with support for the old filter until deprecated and removed.

3. Changing the arguments passed to a filter must always be done in a backward compatible way since making it incompatible warrants the use of a new major version.