docs: [FC-0074] add more detailed concepts on events #406
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
changed the title
mariajgrimaldi
force-pushed
the
MJG/improve-concepts-docs
branch
from
664f78d
to
a18bcb3
Compare
mariajgrimaldi
force-pushed
the
MJG/improve-concepts-docs
branch
from
24571aa
to
655fa5e
Compare
|
@sarina @Apgomeznext: here's the WIP I've been working on for the 1.1 Improve Definitions and Update Outdated References in the Framework project feature. I discussed with AnaP having feedback loops within the maintenance team about the documents' content. She'd get involved to review the document structure once she has the capacity for the project. So, early feedback is welcome. |
mariajgrimaldi
force-pushed
the
MJG/improve-concepts-docs
branch
from
48f6461
to
54b7299
Compare
mariajgrimaldi
changed the title
mariajgrimaldi
changed the title
mariajgrimaldi
changed the title
mariajgrimaldi
changed the title
docs/concepts/openedx-events.rst
Outdated
|
|
||
| Django includes a “signal dispatcher” which helps decoupled applications get notified when actions occur elsewhere in the framework. In a nutshell, signals allow certain senders to notify a set of receivers that some action has taken place. They’re especially useful when many pieces of code may be interested in the same events. | ||
|
|
||
| Events are primarily used as a communication method between components within the same application process or with external services using the Event Bus technology, making them the standard communication mechanism within the Open edX ecosystem. |
There was a problem hiding this comment.
Maybe have "Event Bus" link to documentation on the event bus?
There was a problem hiding this comment.
Done: 6926b20#diff-982f9d143e6afcea5b84eeb1ea3c3fb5412239c1968359fab161cb4af58e9b63R62
But the only available docs we have to date about the event bus is a confluence document, so that's what I linked: https://openedx.atlassian.net/wiki/spaces/AC/pages/3508699151/How+to+start+using+the+Event+Bus. Once we move those documents here, I'll update the references.
docs/concepts/openedx-events.rst
Outdated
|
|
||
| The event execution process follows these steps: | ||
|
|
||
| 1. An application component emits an event by calling the ``send_event`` method implemented by ``OpenEdxPublicEvents``, which calls the Django signal ``send`` method under the hood. |
There was a problem hiding this comment.
| 1. An application component emits an event by calling the ``send_event`` method implemented by ``OpenEdxPublicEvents``, which calls the Django signal ``send`` method under the hood. | |
| #. An Open edX application component emits an event by calling the ``send_event`` method implemented by ``OpenEdxPublicEvents``, which calls the Django signal ``send`` method under the hood. | |
Using #. will auto-make a numbered list in rST. You need to include a blank line after each bullet point.
There was a problem hiding this comment.
Thanks for the suggestion! I already applied the change: 6926b20#diff-982f9d143e6afcea5b84eeb1ea3c3fb5412239c1968359fab161cb4af58e9b63R32-R47
docs/concepts/openedx-events.rst
Outdated
|
|
||
| 1. An application component emits an event by calling the ``send_event`` method implemented by ``OpenEdxPublicEvents``, which calls the Django signal ``send`` method under the hood. | ||
| 2. The class generates Open edX-specific metadata for the event on the fly, like the event version or the timestamp when the event was sent. The event receivers use this metadata during their processing. | ||
| 3. We call the ``send`` method from Django signals, which allows us to use the same Django signals registry for receiver management. |
There was a problem hiding this comment.
There is no we. I changed it: 6926b20#diff-982f9d143e6afcea5b84eeb1ea3c3fb5412239c1968359fab161cb4af58e9b63R31
docs/concepts/openedx-events.rst
Outdated
| 1. An application component emits an event by calling the ``send_event`` method implemented by ``OpenEdxPublicEvents``, which calls the Django signal ``send`` method under the hood. | ||
| 2. The class generates Open edX-specific metadata for the event on the fly, like the event version or the timestamp when the event was sent. The event receivers use this metadata during their processing. | ||
| 3. We call the ``send`` method from Django signals, which allows us to use the same Django signals registry for receiver management. | ||
| 4. The event receivers registered by the Django signals registry mechanism for the emitted event are executed. |
There was a problem hiding this comment.
What does it mean to register an event receiver? Maybe link to documentation on this?
There was a problem hiding this comment.
Thank you for the suggestion. I added a reference to how to listen to signals in Django: 6926b20#diff-982f9d143e6afcea5b84eeb1ea3c3fb5412239c1968359fab161cb4af58e9b63R63
docs/concepts/openedx-events.rst
Outdated
| Here is an example of an event in action: | ||
|
|
||
| 1. A user enrolls in a course, `triggering the COURSE_ENROLLMENT_CREATED event`_. This event includes information about the user, course, and enrollment details. | ||
| 2. A `signal receiver listening`_ for the ``COURSE_ENROLLMENT_CREATED`` event is called and processes the event data. |
There was a problem hiding this comment.
This link is a little confusing, because the text is generic but you're referencing a specific handler. How about:
| 2. A `signal receiver listening`_ for the ``COURSE_ENROLLMENT_CREATED`` event is called and processes the event data. | |
| #. A signal receiver listening for the ``COURSE_ENROLLMENT_CREATED`` event is called and processes the event data. In this case, it would be the `course_enrollment_post_save receiver`_. | |
docs/concepts/openedx-events.rst
Outdated
| 5. Each event receivers performs additional processing or triggers other actions based on the event data. | ||
| 6. The event is considered complete once all registered signal receivers have executed. | ||
|
|
||
| Here is an example of an event in action: |
There was a problem hiding this comment.
| Here is an example of an event in action: | |
| Here is an example of an event that triggers email in response to course enrollment in action: |
There was a problem hiding this comment.
I updated the step by step with a more accurate description, could you review it again?
docs/concepts/openedx-events.rst
Outdated
| 1. A user enrolls in a course, `triggering the COURSE_ENROLLMENT_CREATED event`_. This event includes information about the user, course, and enrollment details. | ||
| 2. A `signal receiver listening`_ for the ``COURSE_ENROLLMENT_CREATED`` event is called and processes the event data. | ||
| 3. The signal receiver sends a notification to the user's email confirming their enrollment in the course. | ||
| 4. The event is considered complete once the signal receiver has finished processing the event. |
There was a problem hiding this comment.
Is there code or something that "considers" the event complete? I guess I don't know exactly what this means.
There was a problem hiding this comment.
Thank you for catching this. I meant something like:
The event processing is complete once all signal receivers have finished executing, so the application continues its execution...
But that sounds way more complex than it actually is, so I changed it: 6926b20#diff-982f9d143e6afcea5b84eeb1ea3c3fb5412239c1968359fab161cb4af58e9b63R37
docs/concepts/openedx-events.rst
Outdated
| How are Open edX Events used? | ||
| ----------------------------- | ||
|
|
||
| Developers can create receivers for Open edX Events by implementing Django signal receivers that respond to these events emitted by the Open edX platform. These signal receivers can be registered using Django's signal mechanism, allowing them to listen for events and execute custom logic in response. |
There was a problem hiding this comment.
I think it would be good to include some detail about how you don't need to modify code within the openedx github org to achieve this. Could we link out to some third-party examples?
There was a problem hiding this comment.
Absolutely! I'm currently working on a list of use cases. In the next few hours, I'll link the PR here in this comment.
I'll link the PR here in this comment tomorrow.
Description
This PR improves the concept section of the documentation by adding a new document dedicated only to Open edX Events.
Initially, I also added two additional modifications:
Which I later dropped in favor of centralizing shared documentation docs.openedx.org and avoiding duplication across repos: So I'll be moving those docs to docs.openedx.org, Here's the PR for the implementation: openedx/docs.openedx.org#599
For more details on the decision, please see this thread.