docs: [FC-0074] centralize docs for the hooks extension framework #599
Conversation
openedx-webhooks
added
the
open-source-contribution
|
Thanks for the pull request, @mariajgrimaldi! What's next?Please work through the following steps to get your changes ready for engineering review: 🔘 Get product approvalIf you haven't already, check this list to see if your contribution needs to go through the product review process.
🔘 Provide contextTo help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:
🔘 Get a green buildIf one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green. 🔘 Let us know that your PR is ready for review:Who will review my changes?This repository is currently maintained by Where can I find more information?If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:
When can I expect my changes to be merged?Our goal is to get community contributions seen and reviewed as efficiently as possible. However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:
💡 As a result it may take up to several weeks or months to complete a review and merge your PR. |
mariajgrimaldi
force-pushed
the
MJG/hooks
branch
from
5f59e21
to
9510dc8
Compare
mariajgrimaldi
changed the title
| @@ -0,0 +1,155 @@ | |||
| ========================= | |||
| Hooks Extension Framework | |||
| ========================= | |||
There was a problem hiding this comment.
| ========================= | |
| ######################### |
In docs.openedx.org, we use the following headings:
H1: # (4 lines in the character)
H2: * (3 lines)
H3: = (2 lines)
H4: -
| ========================= | ||
|
|
||
| What is the Hooks Extension Framework? | ||
| ======================================= |
There was a problem hiding this comment.
| ======================================= | |
| ***************************************************** |
|
|
||
| Based on the `open-closed principle`_, this framework aims to extend the Open edX platform in a maintainable way without modifying its core. The main goal is to leverage the existing extension capabilities provided by the plugin architecture, allowing developers to implement new features to fit customer needs while reducing the need for core modifications and minimizing maintenance efforts. | ||
|
|
||
| Hooks are a list of places in the Open edX platform where externally defined functions can take place. These functions may alter what the user sees or experiences on the platform, while in other cases, they act as notifications. All hooks are designed to be extended through `Open edX Django plugins`_ and configurations. |
There was a problem hiding this comment.
| Hooks are a list of places in the Open edX platform where externally defined functions can take place. These functions may alter what the user sees or experiences on the platform, while in other cases, they act as notifications. All hooks are designed to be extended through `Open edX Django plugins`_ and configurations. | |
| Hooks are places in the Open edX platform where externally defined functions can take place. These functions may alter what the user sees or experiences on the platform, while in other cases, they act as notifications. All hooks are designed to be extended through `Open edX Django plugins`_ and configurations. |
| * `openedx-filters`_ | ||
| * `openedx-events`_ | ||
|
|
||
| The main goal of the framework is that developers can use it to change the platform's functionality as needed and still migrate to newer Open edX releases with little to no development effort. So, the framework is designed with stability in mind, meaning it is versioned and backward compatible as much as possible. |
There was a problem hiding this comment.
| The main goal of the framework is that developers can use it to change the platform's functionality as needed and still migrate to newer Open edX releases with little to no development effort. So, the framework is designed with stability in mind, meaning it is versioned and backward compatible as much as possible. | |
| The framework's main goal is to empower developers to change the platform's functionality as needed while enabling them to migrate to newer Open edX releases with little to no development effort. The framework is designed with stability in mind, meaning it is versioned and backward compatible as much as possible. |
| .. _open-closed principle: https://docs.openedx.org/projects/edx-platform/en/open-release-quince.master/concepts/extension_points.html | ||
|
|
||
| Why adopt the Hooks Extension Framework? | ||
| ======================================== |
| .. _how to implement event receivers: https://docs.openedx.org/projects/openedx-events/en/latest/how-tos/using-events.html#receiving-events | ||
|
|
||
| When to use an Open edX Filter? | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
There was a problem hiding this comment.
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| ----------------------------------------- |
| When to use an Open edX Event? | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| Use an Open edX Event when but not limited to: |
There was a problem hiding this comment.
| Use an Open edX Event when but not limited to: | |
| A developer might use an Open edX Event in order to perform the following actions. Note that this is not an exhaustive list. |
|
|
||
| You can review the `Open edX Events`_ documentation for more information on `how to use events`_ in your project. This documentation includes a `list of available events`_ and `how to implement event receivers`_. | ||
|
|
||
| .. _Open edX Events: https://docs.openedx.org/projects/openedx-events/en/latest/ |
There was a problem hiding this comment.
This is the second definition of this in the document. I suggest compiling your links at the very end of the document, rather than the end of each section, to avoid duplicates.
| When to use an Open edX Filter? | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| Use an Open edX Filter when but not limited to: |
There was a problem hiding this comment.
| Use an Open edX Filter when but not limited to: | |
| A developer might use an Open edX Filter in order to perform the following actions. Note that this is not an exhaustive list.``` |
| Use an Open edX Filter when but not limited to: | ||
|
|
||
| - Enrich the data or parameters passed to a specific component, e.g., fetch reusable LTI configurations from external plugins. | ||
| - Intercept and modify the input of a specific component, e.g., include "Edit" link to an HTML block if certain conditions are met. |
There was a problem hiding this comment.
I'm not sure this is the best example of modifying a component. What are some others?
There was a problem hiding this comment.
All these examples were extracted from a list of real-life use cases we've compiled: https://github.com/mariajgrimaldi/openedx-events-filters-analysis/blob/main/docs/Extensions_built_using_Hooks_Extensions_Framework.pdf. Since I'm writing the use-case list, that is just a filtered version of that document, I'll get some examples from there instead.
Description
This PR adds documentation about the Hooks Extension Framework under the developers section to centralize common concepts between Open edX Events and filters, such as framework overview, differences, comparisons, etc.
You can see the docs rendered here: https://docsopenedxorg--599.org.readthedocs.build/en/599/developers/concepts/index.html
The documentation in https://github.com/openedx/edx-platform/tree/master/docs/hooks should be removed after this gets merged. What this docs is missing from edx-platform guides, it's the index of filters and events within edx-platform:
https://github.com/openedx/edx-platform/blob/master/docs/hooks/filters.rst#index-of-filters
https://github.com/openedx/edx-platform/blob/master/docs/hooks/events.rst#index-of-events
This PR will not replace those indexes since they need extra effort to keep up to date, making the contribution process more cumbersome since we will need to update them here each time a new event/filter is added to a service. I prefer enhancing the current list of events and filters in each repo to reference in some way where they're being used instead.