Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: [FC-0074] add note about decisions documented in each hooks repositories #662

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+26 −0
Open

docs: [FC-0074] add note about decisions documented in each hooks repositories #662

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions oeps/architectural-decisions/oep-0041-arch-async-server-event-messaging.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -475,10 +475,16 @@ Having a clearly defined set of events would allow for simpler third party
integration in areas like student learner event processing and course catalog
management.

------------

.. note:: All future decisions related to :doc:`Open edX Events <openedx-events:index>` that adhere to these guidelines for asynchronous event messaging will now be documented and made publicly available through the Architectural Decision Records (ADRs) in :doc:`Open edX Events ADRs <openedx-events:decisions/index>`. This includes decisions regarding the Event Bus, schema format, serialization, evolution, and design practices for event-driven architecture.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reading this gave me additional ideas that you may like or not like.

  1. This reads like a small decision. I’m wondering if there could be a brief OEP that describes this decision named “Event Related Decision Records”, or “Event and Filter…” or “Hook, Event and Filter…” that details this change, and notes could point to this OEP?
  2. Maybe this won’t be the last time we choose a library repo for housing OEP-esque ADRs on a topic? We could consider updating OEP-19 with this as an option, or an OEP-19 sub ADR, and also list all the current cases as an index.

These are just ideas, and they could influence how we add the notes. That said, we could make these notes the first iteration.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I disagree with this - I think that's adding too much process that no one will ultimately end up reading/needing. I think this note in the OEP is enough. I ran this by Feanil and Kyle and they agree with me, as well.


**************
Change History
**************

2024-01-14: Added note about decisions related to Open edX Events being documented and made publicly available through the Architectural Decision Records (ADRs) in the repository.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There may be more places that warrant this change, but “the repository” is vague and by default might mean “this repository”, but it doesn’t.

Suggested change
2024-01-14: Added note about decisions related to Open edX Events being documented and made publicly available through the Architectural Decision Records (ADRs) in the repository.
2024-01-14: Added note about decisions related to Open edX Events being documented and made publicly available through the Architectural Decision Records (ADRs) in the openedx-events repository.


2022-01-09: Clarified that time field could be based on updated_at time when appropriate.

2022-03-24: Enhance "Architectural Goals" section and minor edits.
Expand Down
5 changes: 5 additions & 0 deletions oeps/architectural-decisions/oep-0050-hooks-extension-framework.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -263,9 +263,14 @@ The current documentation for the Hooks Extension Framework can be found at `Ope

.. _Open edX Guides Hooks: https://github.com/openedx/edx-platform/tree/master/docs/guides/hooks

.. note:: All decisions related to Open edX Events and Filters will now be documented and made publicly available through their respective Architectural Decision Records (ADRs). For more information, see the :doc:`Open edX Events ADRs <openedx-events:decisions/index>` and :doc:`Open edX Filters ADRs <openedx-filters:decisions/index>`.

Change History
**************

14 January 2025 - Maria Grimaldi
Added note about decisions related to Open edX Events and Filters being documented and made publicly available through the Architectural Decision Records (ADRs) in the repository.

20 July 2022 - Maria Grimaldi
Update OEP-50 with latest documentation.

Expand Down
7 changes: 7 additions & 0 deletions oeps/architectural-decisions/oep-0052-arch-event-bus-architecture.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,8 @@ Decision
.. _ADR on External Event Schema Format: https://openedx-events.readthedocs.io/en/latest/decisions/0005-external-event-schema-format.html
.. _ADR on Event Schema Serialization and Evolution: https://openedx-events.readthedocs.io/en/latest/decisions/0006-event-schema-serialization-and-evolution.html

.. note:: All decisions related to Open edX Events where the event bus key components are implemented will now be documented and made publicly available through the Architectural Decision Records (ADRs) in the repository. For more details, refer to the :doc:`Open edX Events ADRs <openedx-events:decisions/index>`.

Consequences
************

Expand All @@ -108,6 +110,11 @@ Consequences
Change History
**************

2025-01-14
==========

* Added note about decisions related to Open edX Events being documented and made publicly available through the Architectural Decision Records (ADRs) in the repository.

2024-07-09
==========

Expand Down
8 changes: 8 additions & 0 deletions oeps/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -360,6 +360,14 @@
f"https://docs.openedx.org/{rtd_language}/{rtd_version}",
None,
),
"openedx-events": (
f"https://docs.openedx.org/projects/openedx-events/{rtd_language}/latest",
None,
),
"openedx-filters": (
f"https://docs.openedx.org/projects/openedx-filters/{rtd_language}/latest",
None,
),
}

# -- Read the Docs Specific Configuration
Expand Down
Loading