Skip to content

Commit

Permalink
docs: apply suggestions from code review
Browse files Browse the repository at this point in the history
  • Loading branch information
mariajgrimaldi authored Dec 17, 2024
1 parent 684283f commit 724e87f
Showing 1 changed file with 6 additions and 6 deletions.
12 changes: 6 additions & 6 deletions docs/decisions/0016-event-design-practices.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Event Design Practices
Status
------

Proposed
Draft

Context
-------
Expand All @@ -16,15 +16,15 @@ Decision

We have compiled a list of suggested practices taken from `Event-Driven Microservices`_ and the `Event-Driven article`_ that we recommend reviewing and following when designing an Open edX Event and contributing to the library. The goal is to implement events that are consistent with the architecture, reusable, and maintainable over time.

#. An event should describe as accurately as possible what happened (what) with its and why it happened (why). It must contain enough information for consumers to understand the message.
#. Design events to be self-descriptive and self-contained. It should contain all the information necessary about what took place for consumers to react to the event without consulting other data sources.
#. An event should describe as accurately as possible what happened (what) and why it happened (why). It must contain enough information for consumers to understand the message.
#. Design events to be self-descriptive and self-contained. The event should contain all the information necessary about what took place for consumers to react to the event without consulting other data sources.
#. Avoid ambiguous data fields or fields with multiple meaning.
#. Design events with a single responsibility in mind. Each event should represent a single action or fact.
#. Avoid adding flow-control information or business logic to events. Events should be solely a representation of what happened.
#. Design events with a single responsibility in mind. Each event should represent a single action or fact that happened in the system.
#. Avoid adding flow-control information or business logic to events. Events should be solely a representation of what took place.
#. Use appropriate data types and formats for the event fields.
#. Design the event so it is small, well-defined and only contain relevant information. Avoid including unnecessary or unrelated context.
#. Ensure the event carries all necessary data to prevent runtime dependencies with other services.
#. Manage the granularity of the event so it is not too course (generic name with too much information) or too fine-grained (specific name with too little information). It should be expressive enough to be useful.
#. Manage the granularity of the event so it is not too coarse (generic name with too much information) or too fine-grained (specific name with too little information). It should be expressive enough to be useful.
#. 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?

Some of these practices might not be applicable to all events, but they are a good starting point to ensure that the events are consistent and maintainable over time.
Expand Down

0 comments on commit 724e87f

Please sign in to comment.