docs: [FC-0074] add ADR with event design suggestions #438
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
|
FYI @Squirrel18 @Alec4r |
mariajgrimaldi
changed the title
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| - Design events with a single responsibility in mind. Each event should represent a single action or fact that happened in the system. If an event contains multiple actions, consider splitting it into multiple events. For instance, if the course grade is updated to pass or fail, there should be two events: one for the pass action and another for the fail action. | ||
| - Manage the granularity of the event so it is not too coarse (generic with too much information) or too fine-grained (specific with too little information). When making a decision on the granularity of the event, start with the minimum required information for consumers to react to the event and add more information as needed with enough justification. If necessary, leverage API calls from the consumer side to retrieve additional information but always consider the trade-offs of adding dependencies with other services. |
There was a problem hiding this comment.
I agree with the idea of avoid generic events, however, we should also avoid split events like course_passed or course_failed when we could use just course_completed with an status.
could we include a practical example on an appropiate level of granularity?
There was a problem hiding this comment.
I'm interested in understanding why having a status is better. I think that in this case, it'd be easier to consume more granular events than leave the responsibility to the consumer to figure out whether the student passed or failed based on the status.
There was a problem hiding this comment.
I understand your perspective, and I think both approaches have valid use cases depending on the context, let me elaborate on why I suggested using course_completed with a status field and we can discuss further to find a balance
If the event represents a single conceptual action for example: completing a course, having one event like course_completed with a clear status passed, failed, etc. could simplify the producer's logic and reduce event proliferation and for consumers, interpreting the status field is relatively straightforward if it's well-documented and includes only a few well-defined values, however if different consumers need to handle passed and failed cases in significantly different ways, separate those events might reduce complexity for them but emitting separate events like course_passed and course_failed could also create challenges such as needing to ensure mutual exclusivty.
So in cases like this I think We could start with course_completed and a status field, ensuring it is well-documented and strictly validted and if in the future we observe a clear need for distinct event flows We could introduce the more granular events without breaking existing consumers.
There was a problem hiding this comment.
In the example we're using, I still think it'd be more straightforward to send smaller and more specific events. As I see it, course completion and grade passing would be two different critical facts happening in the system; therefore, they should be independent. This is more of a question of what consumers would want with a course completion event or a course passing status change.
In any case, these are the only suggestions that should be evaluated for each case. We currently have an event called COURSE_PASSING_STATUS_UPDATED which uses a similar flow control status field called is_passing. In that case, given that the status is directly related to the event, using a status field is acceptable. What do you think? Should we maybe use a rule of thumb indicating that an event can be split into more events, given that they could communicate more facts of the system?
There was a problem hiding this comment.
I added some examples illustrating the granularity I'm referring to: https://github.com/openedx/openedx-events/pull/438/files#diff-bdc081c0ccc9885672f08f8b2c853ca7ce8a068db2cb2497d11e04b19013e19aR88-R112
| ~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| - When designing an event, consider the consumers that will be using it. What information do they need to react to the event? What data is necessary for them to process the event? | ||
| - Design events carefully from the start to minimize breaking changes for consumers, although it is not always possible to avoid breaking changes. |
There was a problem hiding this comment.
will it be necessary to version events to handle event changes, or what is the plan for handling event changes?
There was a problem hiding this comment.
Events are versioned by definition, see this ADR for more info. As for the evolution of the events schema, this other ADR describes what the behavior is supposed to be: https://github.com/openedx/openedx-events/blob/main/docs/decisions/0006-event-schema-serialization-and-evolution.rst#decision, although according to this comment the ADR might be outdated -- I'll be working on updating it. The reality is that we haven't needed to change an event definition in any way that's breaking.
There was a problem hiding this comment.
@robrap: Can you help us figure out what needs to change from the ADR-0006? I could do it, but I need more context to do it effectively.
Description
This PR adds an ADR with suggestions on how to design a new event based on the Building Event-Driven Microservices 3rd chapter about Communication and Data Contracts and Martin Fowler's Event Driven article. I'm proposing that these practices be considered when implementing new events, but they should NOT be considered standards that all events should strictly follow. Also, I'm not saying either that all the existing events in the library comply (or should) with these practices.
This document will be used as a reference in the How to Create a New Event guide. I'm currently validating these items while I write the guide, making sure these suggestions are clear enough to follow. You can review it here: #439
Testing instructions
Review here: https://docsopenedxorg--438.org.readthedocs.build/projects/openedx-events/en/438/decisions/0016-event-design-practices.html
Deadline
None
Checklists
Check off if complete or not applicable:
Merge Checklist:
Post Merge:
finished.