From 65f1156f84bd32fc7a8097c233d8e2a02605b07f Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Mon, 18 Nov 2024 18:43:07 +0100 Subject: [PATCH 1/6] docs: add comparison table between the framework and forking openedx --- .../concepts/hooks_extension_framework.rst | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/source/developers/concepts/hooks_extension_framework.rst b/source/developers/concepts/hooks_extension_framework.rst index 8f7c2cfe..56cba47c 100644 --- a/source/developers/concepts/hooks_extension_framework.rst +++ b/source/developers/concepts/hooks_extension_framework.rst @@ -156,6 +156,39 @@ Filters are useful when you need an immediate response that directly modifies th We encourage you to review the list of use cases for events and filters to draw inspiration from real-life scenarios and see if your use case aligns with any of them. Also, maybe your feature can be implementing using the framework but there's not an available event or filter for it yet. In that case, consider proposing a new event or filter to the community! +The Framework vs Forking the Open edX Platform +********************************************** + +The Hooks Extension Framework is designed to provide a stable and maintainable way to extend the Open edX platform without modifying its core. This approach is in contrast to forking the platform, which involves creating a separate version that separates from the core codebase. Here is a comparison table of the two approaches: + ++--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| | **Open edX Events and Filters** | **Forking** | ++====================================================================+===============================================================================================================+====================================================================================================================================+ +| **Purpose** | Allow extending functionality of the Open edX platform without modifying the | Modify the code directly to meet specific needs. | +| | core codebase but by leveraging and configurations. | | ++--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| **Advantages** | - More decoupled implementations. | - Full control of the platform behavior. | +| | - Decreased maintenance burden of the platform, maintenance efforts are centered on plugins. | - No restrictions from what can be changed. | +| | - Enables reusable and configurable behavior across the platform. | - Suitable for highly customized use cases. | +| | - Easier to maintain long-term due to backward compatibility and versioning policies. | | ++--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| **Disadvantages** | - Can increase complexity in debugging and maintenance because it adds more processing layers. | - Separation from the core makes long-term maintenance challenging. | +| | - Limited by existing events and filters available in the Open edX ecosystem. | - High maintenance burden for upgrades and compatibility. | +| | - Might increase complexity in plugins for highly customized features. | - Requires deep understanding of the platform to modify it correctly. | +| | - Might introduce an edx-platform dependency into plugins, mainly when using filters. | | ++--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| **Performance Impact** | Medium to high, as events and filters execute within the caller process. Although events are designed so | High, as changes directly impact the Open edX platform (edx-platform or other IDAs) and may require additional testing, monitoring,| +| | receivers can trigger asynchronous tasks for improved performance. | and performance considerations of new added code and for the integration itself. | ++--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| **Community Compatibility** | High, as the community encourage reusable implementations and the contribution of new extension points. | Low, as changes in forks are usually highly customized not designed for others to reuse. | ++--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| **Implementation Effort** | Low to medium, depending on the complexity of the receiver logic and filter pipelines. | High, as modifications require expertise in the platform and increase technical debt. | ++--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| **Upgrade Compatibility** | High, due to backward compatibility policies. | Low, as forks must manually integrate their changes with the Open edX platform for each new release. | ++--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ + +When implementing a new feature, consider the advantages and disadvantages of each approach to determine the best fit for your use case and long-term goals. + .. _Open edX Django plugins: https://edx.readthedocs.io/projects/edx-django-utils/en/latest/plugins/readme.html .. _openedx-filters: https://github.com/openedx/openedx-filters .. _openedx-events: https://github.com/openedx/openedx-events From bb6e9ad79c4ef72bc054c18c4c66a2f3ab277af9 Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Thu, 21 Nov 2024 19:18:25 +0100 Subject: [PATCH 2/6] docs: add reference to contribute features --- source/developers/concepts/hooks_extension_framework.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/developers/concepts/hooks_extension_framework.rst b/source/developers/concepts/hooks_extension_framework.rst index 56cba47c..1da45326 100644 --- a/source/developers/concepts/hooks_extension_framework.rst +++ b/source/developers/concepts/hooks_extension_framework.rst @@ -187,7 +187,7 @@ The Hooks Extension Framework is designed to provide a stable and maintainable w | **Upgrade Compatibility** | High, due to backward compatibility policies. | Low, as forks must manually integrate their changes with the Open edX platform for each new release. | +--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -When implementing a new feature, consider the advantages and disadvantages of each approach to determine the best fit for your use case and long-term goals. +When implementing a new feature, consider the advantages and disadvantages of each approach to determine the best fit for your use case and long-term goals. If you think your feature can be part of the core instead of an extension, consider proposing it as a new feature in the Open edX platform. .. _Open edX Django plugins: https://edx.readthedocs.io/projects/edx-django-utils/en/latest/plugins/readme.html .. _openedx-filters: https://github.com/openedx/openedx-filters From b8d7719578bc601be088a74ebc78bc1387d16a7f Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Tue, 26 Nov 2024 12:51:46 +0100 Subject: [PATCH 3/6] refactor: address PR reviews --- .../concepts/hooks_extension_framework.rst | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/source/developers/concepts/hooks_extension_framework.rst b/source/developers/concepts/hooks_extension_framework.rst index 1da45326..53e2e4ff 100644 --- a/source/developers/concepts/hooks_extension_framework.rst +++ b/source/developers/concepts/hooks_extension_framework.rst @@ -159,13 +159,13 @@ We encourage you to review the list of use cases for events and filters to draw The Framework vs Forking the Open edX Platform ********************************************** -The Hooks Extension Framework is designed to provide a stable and maintainable way to extend the Open edX platform without modifying its core. This approach is in contrast to forking the platform, which involves creating a separate version that separates from the core codebase. Here is a comparison table of the two approaches: +The Hooks Extension Framework is designed to provide a stable and maintainable way to extend the Open edX platform without modifying its core. This approach is in contrast to forking the platform, which involves creating a separate version that diverges from the core codebase. Here is a comparison table of the two approaches: +--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ | | **Open edX Events and Filters** | **Forking** | +====================================================================+===============================================================================================================+====================================================================================================================================+ | **Purpose** | Allow extending functionality of the Open edX platform without modifying the | Modify the code directly to meet specific needs. | -| | core codebase but by leveraging and configurations. | | +| | core codebase but by leveraging plugins and configurations. | | +--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ | **Advantages** | - More decoupled implementations. | - Full control of the platform behavior. | | | - Decreased maintenance burden of the platform, maintenance efforts are centered on plugins. | - No restrictions from what can be changed. | @@ -173,21 +173,20 @@ The Hooks Extension Framework is designed to provide a stable and maintainable w | | - Easier to maintain long-term due to backward compatibility and versioning policies. | | +--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ | **Disadvantages** | - Can increase complexity in debugging and maintenance because it adds more processing layers. | - Separation from the core makes long-term maintenance challenging. | -| | - Limited by existing events and filters available in the Open edX ecosystem. | - High maintenance burden for upgrades and compatibility. | +| | - Limited by existing events and filters available in the Open edX ecosystem, but new events and filters can | - High maintenance burden for upgrades and compatibility. | +| | be proposed and added to the framework. | - Requires manual integration with the Open edX platform for each new release. | | | - Might increase complexity in plugins for highly customized features. | - Requires deep understanding of the platform to modify it correctly. | | | - Might introduce an edx-platform dependency into plugins, mainly when using filters. | | +--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| **Performance Impact** | Medium to high, as events and filters execute within the caller process. Although events are designed so | High, as changes directly impact the Open edX platform (edx-platform or other IDAs) and may require additional testing, monitoring,| -| | receivers can trigger asynchronous tasks for improved performance. | and performance considerations of new added code and for the integration itself. | +| **Community Compatibility** | High, as the community encourages reusable implementations and the contribution of new extension points. | Low, as changes in forks are usually highly customized not designed for others to reuse. | +--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| **Community Compatibility** | High, as the community encourage reusable implementations and the contribution of new extension points. | Low, as changes in forks are usually highly customized not designed for others to reuse. | -+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| **Implementation Effort** | Low to medium, depending on the complexity of the receiver logic and filter pipelines. | High, as modifications require expertise in the platform and increase technical debt. | +| **Implementation Effort** | Low to medium, depending on the complexity of the receiver logic and filter pipelines. | High, as modifications require expertise in the platform and increases technical debt. Also, changes may require additional testing| +| | | and monitoring to ensure integration compatibility with the Open edX platform. | +--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ | **Upgrade Compatibility** | High, due to backward compatibility policies. | Low, as forks must manually integrate their changes with the Open edX platform for each new release. | +--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -When implementing a new feature, consider the advantages and disadvantages of each approach to determine the best fit for your use case and long-term goals. If you think your feature can be part of the core instead of an extension, consider proposing it as a new feature in the Open edX platform. +When implementing a new feature, consider the advantages and disadvantages of each approach to determine the best fit for your use case and long-term goals. If you think your feature should be part of the core instead of an extension, consider making a `Product Proposal`_. .. _Open edX Django plugins: https://edx.readthedocs.io/projects/edx-django-utils/en/latest/plugins/readme.html .. _openedx-filters: https://github.com/openedx/openedx-filters From d4266da384e73d2dd6713fe1a897503a19c0ab4c Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Mon, 9 Dec 2024 14:00:31 +0100 Subject: [PATCH 4/6] docs: clarify edx-platform dependency in plugins --- source/developers/concepts/hooks_extension_framework.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/source/developers/concepts/hooks_extension_framework.rst b/source/developers/concepts/hooks_extension_framework.rst index 53e2e4ff..35bdd0ca 100644 --- a/source/developers/concepts/hooks_extension_framework.rst +++ b/source/developers/concepts/hooks_extension_framework.rst @@ -173,10 +173,11 @@ The Hooks Extension Framework is designed to provide a stable and maintainable w | | - Easier to maintain long-term due to backward compatibility and versioning policies. | | +--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ | **Disadvantages** | - Can increase complexity in debugging and maintenance because it adds more processing layers. | - Separation from the core makes long-term maintenance challenging. | -| | - Limited by existing events and filters available in the Open edX ecosystem, but new events and filters can | - High maintenance burden for upgrades and compatibility. | -| | be proposed and added to the framework. | - Requires manual integration with the Open edX platform for each new release. | +| | - Limited by existing events and filters available in the Open edX ecosystem, although new events and | - High maintenance burden for upgrades and compatibility. | +| | filters can be proposed and added to the framework. | - Requires manual integration with the Open edX platform for each new release. | | | - Might increase complexity in plugins for highly customized features. | - Requires deep understanding of the platform to modify it correctly. | -| | - Might introduce an edx-platform dependency into plugins, mainly when using filters. | | +| | - Although it is not recommended to do so, a plugin developer might introduce an edx-platform dependency, | | +| | mainly when using filters, when there is no alternative for getting certain types of data. | | +--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ | **Community Compatibility** | High, as the community encourages reusable implementations and the contribution of new extension points. | Low, as changes in forks are usually highly customized not designed for others to reuse. | +--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ From 67bd6f7c4060421d7b2dea42c6affffa8a8d6acd Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Tue, 10 Dec 2024 12:05:29 +0100 Subject: [PATCH 5/6] docs: address PR reviews * Address wording suggestion "in contrast of forking" * Remove extra but * Change high -> extreme to suggest that only extreme cases should warrant a fork for new features / behaviors * Split sentence reusable / configurable into two * Remove "correctly" from deep understanding sentence * Add test disadvantage for fork * Add test advantage for fork * Add discoverability note * Suggest looking into the framework before forking --- .../concepts/hooks_extension_framework.rst | 23 +++++++++++-------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/source/developers/concepts/hooks_extension_framework.rst b/source/developers/concepts/hooks_extension_framework.rst index 35bdd0ca..51f4eb7c 100644 --- a/source/developers/concepts/hooks_extension_framework.rst +++ b/source/developers/concepts/hooks_extension_framework.rst @@ -159,27 +159,30 @@ We encourage you to review the list of use cases for events and filters to draw The Framework vs Forking the Open edX Platform ********************************************** -The Hooks Extension Framework is designed to provide a stable and maintainable way to extend the Open edX platform without modifying its core. This approach is in contrast to forking the platform, which involves creating a separate version that diverges from the core codebase. Here is a comparison table of the two approaches: +The Hooks Extension Framework is designed to provide a stable and maintainable way to extend the Open edX platform without modifying its core. This approach stands in opposition to the practice of forking, which involves creating a separate version that diverges from the core codebase. Here is a comparison table of the two approaches: +--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ | | **Open edX Events and Filters** | **Forking** | +====================================================================+===============================================================================================================+====================================================================================================================================+ | **Purpose** | Allow extending functionality of the Open edX platform without modifying the | Modify the code directly to meet specific needs. | -| | core codebase but by leveraging plugins and configurations. | | +| | core codebase by leveraging plugins and configurations. | | +--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ | **Advantages** | - More decoupled implementations. | - Full control of the platform behavior. | | | - Decreased maintenance burden of the platform, maintenance efforts are centered on plugins. | - No restrictions from what can be changed. | -| | - Enables reusable and configurable behavior across the platform. | - Suitable for highly customized use cases. | +| | - Enables reusable behavior across the ecosystem and community. | - Suitable for extremely customized use cases. | +| | - Enables configurable behavior across the platform. | | | | - Easier to maintain long-term due to backward compatibility and versioning policies. | | +| | - Easier to test due to more contained implementations. | | +--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| **Disadvantages** | - Can increase complexity in debugging and maintenance because it adds more processing layers. | - Separation from the core makes long-term maintenance challenging. | +| **Disadvantages** | - Can increase complexity in debugging and maintenance because it adds more processing layers. | - Separation from the separation from the upstream project makes long-term maintenance challenging. | | | - Limited by existing events and filters available in the Open edX ecosystem, although new events and | - High maintenance burden for upgrades and compatibility. | | | filters can be proposed and added to the framework. | - Requires manual integration with the Open edX platform for each new release. | -| | - Might increase complexity in plugins for highly customized features. | - Requires deep understanding of the platform to modify it correctly. | -| | - Although it is not recommended to do so, a plugin developer might introduce an edx-platform dependency, | | -| | mainly when using filters, when there is no alternative for getting certain types of data. | | +| | - Might increase complexity in plugins for highly customized features. | - Requires deep understanding of the platform to modify it. | +| | - Although it is not recommended to do so, a plugin developer might introduce an edx-platform dependency, | - Not being able to be reused by the community. | +| | mainly when using filters, when there is no alternative for getting certain types of data. | - Difficult to test in isolation due to highly coupled implementations. | +--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| **Community Compatibility** | High, as the community encourages reusable implementations and the contribution of new extension points. | Low, as changes in forks are usually highly customized not designed for others to reuse. | +| **Community Compatibility** | High, as the community encourages reusable implementations and the contribution of new extension points. | Low, as changes in forks are usually extremely customized not designed for others to reuse. Also, | +| | | community discoverability is low when changes are kept in a fork, making it harder to share and collaborate. | +--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ | **Implementation Effort** | Low to medium, depending on the complexity of the receiver logic and filter pipelines. | High, as modifications require expertise in the platform and increases technical debt. Also, changes may require additional testing| | | | and monitoring to ensure integration compatibility with the Open edX platform. | @@ -187,7 +190,9 @@ The Hooks Extension Framework is designed to provide a stable and maintainable w | **Upgrade Compatibility** | High, due to backward compatibility policies. | Low, as forks must manually integrate their changes with the Open edX platform for each new release. | +--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -When implementing a new feature, consider the advantages and disadvantages of each approach to determine the best fit for your use case and long-term goals. If you think your feature should be part of the core instead of an extension, consider making a `Product Proposal`_. +When implementing a new feature, look into how the Hooks Extension Framework can help you extend the platform before considering forking the Open edX platform. You should consider the advantages and disadvantages of each approach to determine the best fit for your use case and long-term goals. + +.. note:: If you think your feature should be part of the core instead of an extension, consider making a `Product Proposal`_. .. _Open edX Django plugins: https://edx.readthedocs.io/projects/edx-django-utils/en/latest/plugins/readme.html .. _openedx-filters: https://github.com/openedx/openedx-filters From 125160543a9dc71125d4e9f81135012a487ee82e Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Tue, 10 Dec 2024 12:30:12 +0100 Subject: [PATCH 6/6] docs: remove deep understanding of the platform disadvantage --- source/developers/concepts/hooks_extension_framework.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/developers/concepts/hooks_extension_framework.rst b/source/developers/concepts/hooks_extension_framework.rst index 51f4eb7c..bcafbe3b 100644 --- a/source/developers/concepts/hooks_extension_framework.rst +++ b/source/developers/concepts/hooks_extension_framework.rst @@ -177,9 +177,9 @@ The Hooks Extension Framework is designed to provide a stable and maintainable w | **Disadvantages** | - Can increase complexity in debugging and maintenance because it adds more processing layers. | - Separation from the separation from the upstream project makes long-term maintenance challenging. | | | - Limited by existing events and filters available in the Open edX ecosystem, although new events and | - High maintenance burden for upgrades and compatibility. | | | filters can be proposed and added to the framework. | - Requires manual integration with the Open edX platform for each new release. | -| | - Might increase complexity in plugins for highly customized features. | - Requires deep understanding of the platform to modify it. | -| | - Although it is not recommended to do so, a plugin developer might introduce an edx-platform dependency, | - Not being able to be reused by the community. | -| | mainly when using filters, when there is no alternative for getting certain types of data. | - Difficult to test in isolation due to highly coupled implementations. | +| | - Might increase complexity in plugins for highly customized features. | - Not being able to be reused by the community. | +| | - Although it is not recommended to do so, a plugin developer might introduce an edx-platform dependency, | - Difficult to test in isolation due to highly coupled implementations. | +| | mainly when using filters, when there is no alternative for getting certain types of data. | | +--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ | **Community Compatibility** | High, as the community encourages reusable implementations and the contribution of new extension points. | Low, as changes in forks are usually extremely customized not designed for others to reuse. Also, | | | | community discoverability is low when changes are kept in a fork, making it harder to share and collaborate. | @@ -190,7 +190,7 @@ The Hooks Extension Framework is designed to provide a stable and maintainable w | **Upgrade Compatibility** | High, due to backward compatibility policies. | Low, as forks must manually integrate their changes with the Open edX platform for each new release. | +--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -When implementing a new feature, look into how the Hooks Extension Framework can help you extend the platform before considering forking the Open edX platform. You should consider the advantages and disadvantages of each approach to determine the best fit for your use case and long-term goals. +When implementing a new feature, look into how the Hooks Extension Framework can help you extend the platform before considering forking the Open edX platform. You should consider the advantages and disadvantages of each approach to determine the best fit for your use case and long-term goals. .. note:: If you think your feature should be part of the core instead of an extension, consider making a `Product Proposal`_.