From 44e89f2e061e35f8c70a0eddbc4c50e71647d284 Mon Sep 17 00:00:00 2001 From: XnpioChV Date: Mon, 12 Jun 2023 19:25:02 -0500 Subject: [PATCH 1/4] docs: ADRs for System-defined taxonomies --- .../0012-system-taxonomy-creation.rst | 44 +++++++++++++++++++ .../0013-system-taxonomy-auto-tagging.rst | 30 +++++++++++++ 2 files changed, 74 insertions(+) create mode 100644 docs/decisions/0012-system-taxonomy-creation.rst create mode 100644 docs/decisions/0013-system-taxonomy-auto-tagging.rst diff --git a/docs/decisions/0012-system-taxonomy-creation.rst b/docs/decisions/0012-system-taxonomy-creation.rst new file mode 100644 index 000000000..24744a84e --- /dev/null +++ b/docs/decisions/0012-system-taxonomy-creation.rst @@ -0,0 +1,44 @@ +12. System-defined Taxonomy & Tags creation +============================================ + +Context +-------- + +The System-defined are closed taxonomies created by the system. Some of this 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 +--------- + +Create a ``Content-side`` class that lives on ``openedx.features.tagging``. +You must create a content-side model for each content and taxonomy to be used. +You can use ``ContentSystemTaxonomyMixin`` and the mixin of the Taxonomy (e.g. ``LanguageSystemTaxonomy``) to create the new class. +Then, all system-defined taxonomies must be created initially in a fixture. + +Each Taxonomy mixin has ``get_tags``; to configure the valid tags, and ``validate_tags``; to check if a list of tags are valid. + +We have two ways to handle tags in this type of 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_tags`` method. For example we can put the Author taxonomy 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 +----------------- + +Auto-generated from the codebase +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Taxonomies that depend on a core data model and it is necessary to create a Tag for each object created. 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..4a0e1ea7a --- /dev/null +++ b/docs/decisions/0013-system-taxonomy-auto-tagging.rst @@ -0,0 +1,30 @@ +13. System-defined automatic tagging +===================================== + +Context +-------- + +One main characteristic of the System-defined is the 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. +After create the ``Content-side`` class, `register a pipeline`_ with the respective filter. +Some filters must to be created, like ``CourseCreation``, ``LibraryCreation``, etc. + +All this logic will be live on ``openedx.features.tagging``. + +Rejected Options +----------------- + +Django Signals +~~~~~~~~~~~~~~ + +Implement a function to add the tag from the content metadata and register that function +as a Django signal. Use 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/tree/a4a192e1cac0b70bed31e0db8e4c4b058848c5c4 +.. _register a pipeline: https://github.com/openedx/edx-platform/blob/40613ae3f47eb470aff87359a952ed7e79ad8555/docs/guides/hooks/filters.rst#implement-pipeline-steps From 8680938e4de7b25b042b521e4a868872002910d0 Mon Sep 17 00:00:00 2001 From: XnpioChV Date: Tue, 13 Jun 2023 13:15:28 -0500 Subject: [PATCH 2/4] docs: Updating System taxonomy creation --- .../0012-system-taxonomy-creation.rst | 36 +++++++++++-------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/docs/decisions/0012-system-taxonomy-creation.rst b/docs/decisions/0012-system-taxonomy-creation.rst index 24744a84e..db9500eee 100644 --- a/docs/decisions/0012-system-taxonomy-creation.rst +++ b/docs/decisions/0012-system-taxonomy-creation.rst @@ -12,33 +12,41 @@ the System-defined taxonomies and their tags. Decision --------- -Create a ``Content-side`` class that lives on ``openedx.features.tagging``. -You must create a content-side model for each content and taxonomy to be used. -You can use ``ContentSystemTaxonomyMixin`` and the mixin of the Taxonomy (e.g. ``LanguageSystemTaxonomy``) to create the new class. -Then, all system-defined taxonomies must be created initially in a fixture. +System-defined Taxonomy creation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Each Taxonomy mixin has ``get_tags``; to configure the valid tags, and ``validate_tags``; to check if a list of tags are valid. +Each System-defined Taxonomy has its own class, which is used for tag validation (e.g. ``LanguageSystemTaxonomy``, ``OrganizationSystemTaxonomy``). +Each has ``get_tags``; to configure the valid tags, and ``validate_tags``; to check if a list of tags are valid. +We need to create an instance of each System-defined Taxonomy in a fixture. This instances will be used on different APIs. -We have two ways to handle tags in this type of taxonomies: +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. -Hardcoded by fixtures/migrations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Tags creation +~~~~~~~~~~~~~~ + +We have two ways to handle Tags in this type of 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 -~~~~~~~~~~~~~~ +**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_tags`` method. For example we can put the Author taxonomy 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. +but we can validate the tags using the ``validate_tags`` 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 ----------------- -Auto-generated from the codebase -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Tags created by Auto-generated from the codebase +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Taxonomies that depend on a core data model and it is necessary to create a Tag for each object created. + + +.. _document number 0013: https://github.com/openedx/openedx-learning/blob/main/docs/decisions/0013-system-taxonomy-auto-tagging.rst From 4082a52c679c5b11cf65a9664476fe43101f0419 Mon Sep 17 00:00:00 2001 From: XnpioChV Date: Tue, 13 Jun 2023 14:13:32 -0500 Subject: [PATCH 3/4] docs: Auto tagging doc updated --- .../0012-system-taxonomy-creation.rst | 16 +++++++++---- .../0013-system-taxonomy-auto-tagging.rst | 23 +++++++++++++++---- 2 files changed, 29 insertions(+), 10 deletions(-) diff --git a/docs/decisions/0012-system-taxonomy-creation.rst b/docs/decisions/0012-system-taxonomy-creation.rst index db9500eee..93034b940 100644 --- a/docs/decisions/0012-system-taxonomy-creation.rst +++ b/docs/decisions/0012-system-taxonomy-creation.rst @@ -16,17 +16,19 @@ System-defined Taxonomy creation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Each System-defined Taxonomy has its own class, which is used for tag validation (e.g. ``LanguageSystemTaxonomy``, ``OrganizationSystemTaxonomy``). -Each has ``get_tags``; to configure the valid tags, and ``validate_tags``; to check if a list of tags are valid. +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 +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 in this type of taxonomies: +We have two ways to handle Tags creation and validation for System-defined Taxonomies: **Hardcoded by fixtures/migrations** @@ -36,7 +38,7 @@ We have two ways to handle Tags in this type of taxonomies: **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_tags`` method. For example we can put the ``AuthorSystemTaxonomy`` associated with +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. @@ -46,7 +48,11 @@ Rejected Options Tags created by Auto-generated from the codebase ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Taxonomies that depend on a core data model and it is necessary to create a Tag for each object created. +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 index 4a0e1ea7a..0c3aa1082 100644 --- a/docs/decisions/0013-system-taxonomy-auto-tagging.rst +++ b/docs/decisions/0013-system-taxonomy-auto-tagging.rst @@ -11,10 +11,21 @@ Decision --------- Use `openedx-filters`_ to call the auto tagging function after content creation/edition. -After create the ``Content-side`` class, `register a pipeline`_ with the respective filter. -Some filters must to be created, like ``CourseCreation``, ``LibraryCreation``, etc. -All this logic will be live on ``openedx.features.tagging``. +Filters +~~~~~~~~ + +It is necessary to create `filters`_ for each content for creation/edition: ``CourseCreation``, ``LibraryCreation``, etc. +This filters will live on ``openedx-filters``. + +Pipelines +~~~~~~~~~~ + +After create the ``Content-side`` class for each content and taxonomy, +create a function inside each class with the logic of the auto tagging. +Then you need to register each class as `a pipeline`_ with the respective filter. + +This pipelines will live on ``openedx.features.tagging`` Rejected Options ----------------- @@ -23,8 +34,10 @@ Django Signals ~~~~~~~~~~~~~~ Implement a function to add the tag from the content metadata and register that function -as a Django signal. Use openedx-filters is better in the edx context, but if there is +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/tree/a4a192e1cac0b70bed31e0db8e4c4b058848c5c4 -.. _register a pipeline: https://github.com/openedx/edx-platform/blob/40613ae3f47eb470aff87359a952ed7e79ad8555/docs/guides/hooks/filters.rst#implement-pipeline-steps +.. _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 From 69ee8dcdd06679d936e1af1fab2d7e192bbc5317 Mon Sep 17 00:00:00 2001 From: XnpioChV Date: Wed, 14 Jun 2023 11:23:34 -0500 Subject: [PATCH 4/4] docs: Nits --- docs/decisions/0012-system-taxonomy-creation.rst | 2 +- docs/decisions/0013-system-taxonomy-auto-tagging.rst | 11 ++++------- 2 files changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/decisions/0012-system-taxonomy-creation.rst b/docs/decisions/0012-system-taxonomy-creation.rst index 93034b940..fe67b6e34 100644 --- a/docs/decisions/0012-system-taxonomy-creation.rst +++ b/docs/decisions/0012-system-taxonomy-creation.rst @@ -4,7 +4,7 @@ Context -------- -The System-defined are closed taxonomies created by the system. Some of this are totally static (e.g Language) +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. diff --git a/docs/decisions/0013-system-taxonomy-auto-tagging.rst b/docs/decisions/0013-system-taxonomy-auto-tagging.rst index 0c3aa1082..74b36bc1f 100644 --- a/docs/decisions/0013-system-taxonomy-auto-tagging.rst +++ b/docs/decisions/0013-system-taxonomy-auto-tagging.rst @@ -4,7 +4,7 @@ Context -------- -One main characteristic of the System-defined is the automatic content tagging. +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 @@ -21,11 +21,8 @@ This filters will live on ``openedx-filters``. Pipelines ~~~~~~~~~~ -After create the ``Content-side`` class for each content and taxonomy, -create a function inside each class with the logic of the auto tagging. -Then you need to register each class as `a pipeline`_ with the respective filter. - -This pipelines will live on ``openedx.features.tagging`` +Auto-tagging pipelines will live under ``openedx.features.tagging``, +registered as `a pipeline`_ with the respective filter. Rejected Options ----------------- @@ -38,6 +35,6 @@ as a Django signal. This works for Django database models, but some of the conte 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/tree/a4a192e1cac0b70bed31e0db8e4c4b058848c5c4 +.. _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