Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: [FC-0074] add comparison table between the framework and forking openedx #617

Merged
merged 6 commits into from
Dec 11, 2024
Merged

docs: [FC-0074] add comparison table between the framework and forking openedx #617

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
65f1156
docs: add comparison table between the framework and forking openedx
mariajgrimaldi Nov 18, 2024
bb6e9ad
docs: add reference to contribute features
mariajgrimaldi Nov 21, 2024
b8d7719
refactor: address PR reviews
mariajgrimaldi Nov 26, 2024
d4266da
docs: clarify edx-platform dependency in plugins
mariajgrimaldi Dec 9, 2024
67bd6f7
docs: address PR reviews
mariajgrimaldi Dec 10, 2024
1251605
docs: remove deep understanding of the platform disadvantage
mariajgrimaldi Dec 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions source/developers/concepts/hooks_extension_framework.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,44 @@ 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 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 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 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 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. | - 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. |
+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+
| **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, 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
.. _openedx-events: https://github.com/openedx/openedx-events
Expand Down