docs: [FC-0074] add more detailed concepts on events #406

mariajgrimaldi · 2024-10-11T13:19:19Z

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:

Update references in the Hooks Extension Framework document and explain why the framework should be adopted.
Adding a new document comparing Open edX Events vs Filters to ease adoption.

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.

openedx-webhooks · 2024-10-11T13:19:23Z

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 approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
- This process (including the steps you'll need to take) is documented here.
If it doesn't, simply proceed with the next step.

🔘 Provide context

To 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:

Dependencies

This PR must be merged before / after / at the same time as ...
Blockers

This PR is waiting for OEP-1234 to be accepted.
Timeline information

This PR must be merged by XX date because ...
Partner information

This is for a course on edx.org.
Supporting documentation
Relevant Open edX discussion forum threads

🔘 Get a green build

If 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 @openedx/hooks-extension-framework. Tag them in a comment and let them know that your changes are ready for review.

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:

The size and impact of the changes that it introduces
The need for product review
Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

docs/concepts/openedx-events.rst

docs/concepts/events-vs-filters.rst

mariajgrimaldi · 2024-10-28T12:57:39Z

@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.

sarina · 2024-11-04T16:27:09Z

docs/concepts/openedx-events.rst

+
+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.


Maybe have "Event Bus" link to documentation on the event bus?

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

sarina · 2024-11-04T16:36:11Z

docs/concepts/openedx-events.rst

+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.


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?

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.

Overall it Looks great now, I'll do a final review once these use cases are in

I haven't had the time to work on this. So I'll be on it today. Thank you for the patience!

Here's the PR with the use cases: #416

mariajgrimaldi · 2024-11-25T13:01:17Z

I'll merge this once the CLA check passes. I'm not sure why it's taking so long.

openedx-webhooks added the open-source-contribution PR author is not from Axim or 2U label Oct 11, 2024

mariajgrimaldi changed the title ~~Mjg/improve concepts docs~~ docs: add more detailed documentation under the concepts section Oct 11, 2024

mariajgrimaldi force-pushed the MJG/improve-concepts-docs branch 2 times, most recently from 24571aa to 655fa5e Compare October 15, 2024 10:26

mariajgrimaldi marked this pull request as ready for review October 15, 2024 10:50

mariajgrimaldi requested a review from a team as a code owner October 15, 2024 10:50

mariajgrimaldi marked this pull request as draft October 15, 2024 12:17

mariajgrimaldi removed the request for review from a team October 15, 2024 12:17

mariajgrimaldi commented Oct 15, 2024

View reviewed changes

docs/concepts/openedx-events.rst Outdated Show resolved Hide resolved

mariajgrimaldi commented Oct 15, 2024

View reviewed changes

docs/concepts/openedx-events.rst Outdated Show resolved Hide resolved

mariajgrimaldi commented Oct 15, 2024

View reviewed changes

docs/concepts/openedx-events.rst Show resolved Hide resolved

mariajgrimaldi commented Oct 15, 2024

View reviewed changes

docs/concepts/events-vs-filters.rst Outdated Show resolved Hide resolved

docs/concepts/events-vs-filters.rst Outdated Show resolved Hide resolved

docs/concepts/events-vs-filters.rst Outdated Show resolved Hide resolved

mariajgrimaldi force-pushed the MJG/improve-concepts-docs branch from 48f6461 to 54b7299 Compare October 28, 2024 18:04

mariajgrimaldi changed the title ~~docs: add more detailed documentation under the concepts section~~ docs: [FC-0074] add more detailed docs under the concepts section Oct 28, 2024

mariajgrimaldi changed the title ~~docs: [FC-0074] add more detailed docs under the concepts section~~ docs: [FC-0074] add detailed concepts on events (what, how, why) Oct 28, 2024

mphilbrick211 added the FC Relates to an Axim Funded Contribution project label Oct 30, 2024

mariajgrimaldi mentioned this pull request Oct 31, 2024

docs: [FC-0074] add new hooks docs in concepts section openedx/edx-platform#35733

Closed

mariajgrimaldi marked this pull request as ready for review November 4, 2024 13:17

mariajgrimaldi changed the title ~~docs: [FC-0074] add detailed concepts on events (what, how, why)~~ docs: [FC-0074] add detailed concepts on events Nov 4, 2024

mariajgrimaldi requested review from a team and sarina November 4, 2024 16:17

mariajgrimaldi changed the title ~~docs: [FC-0074] add detailed concepts on events~~ docs: [FC-0074] add more detailed concepts on events Nov 4, 2024

sarina requested changes Nov 4, 2024

View reviewed changes

mariajgrimaldi mentioned this pull request Nov 4, 2024

docs: [FC-0074] add more detailed docs on filters openedx/openedx-filters#222

Merged

sarina approved these changes Nov 12, 2024

View reviewed changes

mariajgrimaldi requested review from felipemontoya and Ian2012 November 18, 2024 10:21

Ian2012 approved these changes Nov 18, 2024

View reviewed changes

mariajgrimaldi added 26 commits November 25, 2024 13:02

docs: update documentation references

7a96f57

fix: add missing references for links

ffb64da

docs: clarify events-vs-filters.rst

9dfd3a3

docs: remove unused references

36f6aa8

docs: Update openedx-events.rst

27bf392

fix: remove trailing spaces

49ae1af

docs: remove linebreaks to improve rendering

a6c3e63

fix: use correct reference for signal handler

a4c55a7

docs: add reference to how-to use open edx events

e415b70

fix: use relative path for how-tos folder

9791b5b

fix: use html file extension for reference

b58de56

docs: address PR reviews

6b11976

docs: Update hooks-extension-framework.rst

95d72d4

docs: Update hooks-extension-framework.rst

88640cc

docs: Update openedx-events.rst

9869fb7

docs: Update openedx-events.rst

a455a1e

docs: Update openedx-events.rst

f6b9640

refactor: address reviews

cb44992

docs: add why using the framework section

4b33fe2

docs: be consistent with framework name

4550d6d

fix: add correct reference to handler

44f930d

fix: remove trailing space

83816cc

refactor!: drop duplicated documents in favor of centralized docs

7428b89

refactor: address PR reviews

baff218

fix: correctly reference send method from django signals

15c2540

refactor: use double backticks instead of single

1656d67

mariajgrimaldi force-pushed the MJG/improve-concepts-docs branch from 5138df5 to 1656d67 Compare November 25, 2024 12:03

mariajgrimaldi merged commit 328fe14 into main Nov 25, 2024
8 checks passed

mariajgrimaldi deleted the MJG/improve-concepts-docs branch November 25, 2024 13:16

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: [FC-0074] add more detailed concepts on events #406

docs: [FC-0074] add more detailed concepts on events #406

mariajgrimaldi commented Oct 11, 2024 •

edited

Loading

openedx-webhooks commented Oct 11, 2024 •

edited

Loading

mariajgrimaldi commented Oct 28, 2024 •

edited

Loading

sarina Nov 4, 2024

mariajgrimaldi Nov 4, 2024 •

edited

Loading

sarina Nov 4, 2024

mariajgrimaldi Nov 4, 2024 •

edited

Loading

sarina Nov 6, 2024

mariajgrimaldi Nov 7, 2024

mariajgrimaldi Nov 12, 2024

mariajgrimaldi commented Nov 25, 2024


		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.

docs: [FC-0074] add more detailed concepts on events #406

docs: [FC-0074] add more detailed concepts on events #406

Conversation

mariajgrimaldi commented Oct 11, 2024 • edited Loading

Description

openedx-webhooks commented Oct 11, 2024 • edited Loading

What's next?

🔘 Get product approval

🔘 Provide context

🔘 Get a green build

🔘 Let us know that your PR is ready for review:

Who will review my changes?

Where can I find more information?

When can I expect my changes to be merged?

mariajgrimaldi commented Oct 28, 2024 • edited Loading

sarina Nov 4, 2024

Choose a reason for hiding this comment

mariajgrimaldi Nov 4, 2024 • edited Loading

Choose a reason for hiding this comment

sarina Nov 4, 2024

Choose a reason for hiding this comment

mariajgrimaldi Nov 4, 2024 • edited Loading

Choose a reason for hiding this comment

sarina Nov 6, 2024

Choose a reason for hiding this comment

mariajgrimaldi Nov 7, 2024

Choose a reason for hiding this comment

mariajgrimaldi Nov 12, 2024

Choose a reason for hiding this comment

mariajgrimaldi commented Nov 25, 2024

mariajgrimaldi commented Oct 11, 2024 •

edited

Loading

openedx-webhooks commented Oct 11, 2024 •

edited

Loading

mariajgrimaldi commented Oct 28, 2024 •

edited

Loading

mariajgrimaldi Nov 4, 2024 •

edited

Loading

mariajgrimaldi Nov 4, 2024 •

edited

Loading