docs: add open edx event guide

[mariajgrimaldi]

Description:
This PR adds a how-to for new event creation. Its main purpose is to serve as a guide for new contributions to the library.

Dependencies:
None

Installation instructions:
Just documentation.

Testing instructions:
Just documentation.

Reviewers:

• tag reviewer
• tag reviewer

Merge checklist:

• All reviewers approved
• CI build is green
• Version bumped
• Changelog record added
• Documentation updated (not only docstrings)
• Commits are squashed

Post merge:

• Create a tag
• Check new version is pushed to PyPI after tag-triggered build is
  finished.
• Delete working branch (if not needed anymore)

Author concerns:
What else should we add?

[robrap]

Thank you! A nice start to kick this off.

[mariajgrimaldi]

Hi there @robrap! Thanks for the feedback. I'll be addressing your comments on Monday. Sorry for the delay!

[mariajgrimaldi]

FYI @felipemontoya

[openedx-webhooks]

Thanks for the pull request, @mariajgrimaldi!

As a core committer in this repo, you can merge this once the pull request is approved per the core committer reviewer requirements and according to the agreement with your edX Champion.

[robrap]

@mariajgrimaldi: Someone recently thoughts some new events defined in this library would be on the event bus. I haven't quite gotten to the bottom of the confusion, but when I went to send a link to some docs, I realized that this doc never landed. I wonder how quickly we could land this, even if we'd want to improve it in the future. Thanks.

[mariajgrimaldi]

@robrap: hello! Thanks for the reminder, sorry I didn't push this forward. A lot of stuff got in the way. Our maintainer team including myself will allocate some time between this week and next to complete this work, at least until its first version.
I'll be tagging you for feedback if you're okay with it! Thanks

[robrap]

Hello @mariajgrimaldi. No apologies necessary. I look forward to helping land something.

[robrap]

@mariajgrimaldi: Another bit we could add is a reminder to document the event in the service where it is produced, using edx-platform as an example: https://github.com/openedx/edx-platform/blob/f01ef48190c7c4ee6d9e06af4abe21e25fe16dff/docs/guides/hooks/events.rst#index-of-events.

Related:

1. I never remember where to find the index of events. Maybe just having a note in this doc will be a good enough reminder for me? We'll see.
2. Where is the best place to document that a given event is not only implemented in a service, but is also going to the event bus? Would that just be in an index like the link above? Maybe this depends on if we move this to be part of the event definition? At this point, it is just based on someone adding a listener that sends to the event bus.

[mariajgrimaldi]

I'm finally setting aside some time to do this! Thank you so much for your patience.

[mariajgrimaldi]

@robrap:

Another bit we could add is a reminder to document the event in the service where it is produced, using edx-platform as an example: https://github.com/openedx/edx-platform/blob/f01ef48190c7c4ee6d9e06af4abe21e25fe16dff/docs/guides/hooks/events.rst#index-of-events.

Consider it done!

Where is the best place to document that a given event is not only implemented in a service but is also going to the event bus? Would that just be in an index like the link above? Maybe this depends on if we move this to be part of the event definition? At this point, it is just based on someone adding a listener that sends to the event bus.

I added a how-to called Adding a new event to the event bus, what I think we could do is add an extra step to How to add an Open edX Event to a service saying Add event to the event to the event bus if supported and linking it to the how-to.

Also, we could modify that index with a column saying "sent over the event bus" that says yes or no. What do you think?

[mariajgrimaldi]

@robrap: I started addressing your comments! Thank you! I'll let you know when this is ready for review again

[mariajgrimaldi]

@robrap: thank you so much! I think I addressed all your comments. Let me know what you think

[mariajgrimaldi]

I'll be fixing the failing tests later 😅

[robrap]

Thank you for all the work. I’m not sure if I’ll get to review before the end of the conference or not.

[robrap]

Thanks again @mariajgrimaldi.

[robrap]

Looks good to me. Thanks. @ormsbee can let us know if he'd like this to be even stronger, but either way, that doesn't need to block this PR.

[mariajgrimaldi]

@robrap: again, thank you so much for the help! and the patience 😅

[robrap]

Looks great. We can always iterate as-needed. Thanks so much for all the great work!

Not sure if you need to kick off tests again to see if openedx/cla check will work?

[openedx-webhooks]

@mariajgrimaldi 🎉 Your pull request was merged! Please take a moment to answer a two question survey so we can improve your experience in the future.