diff --git a/docs/decisions/0012-system-taxonomy-creation.rst b/docs/decisions/0012-system-taxonomy-creation.rst new file mode 100644 index 000000000..fe67b6e34 --- /dev/null +++ b/docs/decisions/0012-system-taxonomy-creation.rst @@ -0,0 +1,58 @@ +12. System-defined Taxonomy & Tags creation +============================================ + +Context +-------- + +System-defined taxonomies are closed taxonomies created by the system. Some of these are totally static (e.g Language) +and some depends on a core data model (e.g. Organizations). It is necessary to define how to create and validate +the System-defined taxonomies and their tags. + + +Decision +--------- + +System-defined Taxonomy creation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each System-defined Taxonomy has its own class, which is used for tag validation (e.g. ``LanguageSystemTaxonomy``, ``OrganizationSystemTaxonomy``). +Each can overwrite ``get_tags``; to configure the valid tags, and ``validate_object_tag``; to check if a list of tags are valid. +Both functions are implemented on the ``Taxonomy`` base class, but can be overwritten to handle special cases. + +We need to create an instance of each System-defined Taxonomy in a fixture. This instances will be used on different APIs. + +Later, we need to create a ``Content-side`` class that lives on ``openedx.features.tagging`` for each content and taxonomy to be used +(eg. ``CourseLanguageSystemTaxonomy``, ``CourseOrganizationSystemTaxonomy``). +This new class is used to configure the automatic content tagging. You can read the `document number 0013`_ to see this configuration. + +Tags creation +~~~~~~~~~~~~~~ + +We have two ways to handle Tags creation and validation for System-defined Taxonomies: + +**Hardcoded by fixtures/migrations** + +#. If the tags don't change over the time, you can create all on a fixture (e.g Languages). +#. If the tags change over the time, you can create all on a migration. If you edit, delete, or add new tags, you should also do it in a migration. + +**Free-form tags** + +This taxonomy depends on a core data model, but simplifies the creation of Tags by allowing free-form tags, +but we can validate the tags using the ``validate_object_tag`` method. For example we can put the ``AuthorSystemTaxonomy`` associated with +the ``User`` model and use the ``ID`` field as tags. Also we can validate if an ``User`` still exists or has been deleted over time. + + +Rejected Options +----------------- + +Tags created by Auto-generated from the codebase +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Taxonomies that depend on a core data model could create a Tag for each eligible object. +Maintaining this dynamic list of available Tags is cumbersome: we'd need triggers for creation, editing, and deletion. +And if it's a large list of objects (e.g. Users), then copying that list into the Tag table is overkill. +It is better to dynamically generate the list of available Tags, and/or dynamically validate a submitted object tag than +to store the options in the database. + + +.. _document number 0013: https://github.com/openedx/openedx-learning/blob/main/docs/decisions/0013-system-taxonomy-auto-tagging.rst diff --git a/docs/decisions/0013-system-taxonomy-auto-tagging.rst b/docs/decisions/0013-system-taxonomy-auto-tagging.rst new file mode 100644 index 000000000..74b36bc1f --- /dev/null +++ b/docs/decisions/0013-system-taxonomy-auto-tagging.rst @@ -0,0 +1,40 @@ +13. System-defined automatic tagging +===================================== + +Context +-------- + +One main characteristic of system-defined taxonomies is automatic content tagging. +It is necessary to implement this functionality when the associated content is created or edited. + +Decision +--------- + +Use `openedx-filters`_ to call the auto tagging function after content creation/edition. + +Filters +~~~~~~~~ + +It is necessary to create `filters`_ for each content for creation/edition: ``CourseCreation``, ``LibraryCreation``, etc. +This filters will live on ``openedx-filters``. + +Pipelines +~~~~~~~~~~ + +Auto-tagging pipelines will live under ``openedx.features.tagging``, +registered as `a pipeline`_ with the respective filter. + +Rejected Options +----------------- + +Django Signals +~~~~~~~~~~~~~~ + +Implement a function to add the tag from the content metadata and register that function +as a Django signal. This works for Django database models, but some of the content lives in Mongo, +outside of the Django models. Also, using openedx-filters is better in the edx context, but if there is +other no-edX project that need to use ``openedx-tagging``, can use the Django Signals approach. + +.. _openedx-filters: https://github.com/openedx/openedx-filters +.. _filters: https://github.com/openedx/openedx-filters/blob/a4a192e1cac0b70bed31e0db8e4c4b058848c5c4/openedx_filters/learning/filters.py +.. _a pipeline: https://github.com/openedx/edx-platform/blob/40613ae3f47eb470aff87359a952ed7e79ad8555/docs/guides/hooks/filters.rst#implement-pipeline-steps