docs: [FC-0074] use glossary as reference material #221

mariajgrimaldi · 2024-10-15T11:55:05Z

Description

This PR:

Move glossary document to the reference section for better organization.
Use sphinx utilities to implement a glossary.
Reference glossary throughout all documents when needed.

openedx-webhooks · 2024-10-15T11:55:09Z

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.

mariajgrimaldi · 2024-11-04T13:25:45Z

@sarina @Apgomeznext: here's another PR part of the 1.1 Improve Definitions and Update Outdated References in the Framework implementation effort.

…sion

docs/reference/glossary.rst

sarina · 2024-11-04T16:45:25Z

docs/reference/glossary.rst

+     The filter type is a unique identifier for the filter, following a standardized format (e.g., reverse DNS style). This type is used as an index for configuring the filter pipeline and specifies which configuration settings apply to a given filter.
+
+   Filter Exceptions
+     Filters can raise exceptions to control the flow of the pipeline. If a filter raises an exception, the pipeline halts, and the exception becomes the pipeline's output. Exceptions are typically raised when certain conditions specified in the filter's logic are met, signaling an event or state change.


Are exceptions a recommended practice, or should they be avoided except in extreme cases?

We encourage using exceptions when it makes sense considering the use case of the filter. For example, the course enrollment filter has its own exceptions cause some developers might want to stop the enrollment process when a condition is met. But there are other filters, like changing the IDV URL during runtime, where raising an exception doesn't make much sense.

Sounds good - sounds pretty conditional, don't think another note needs to be made.

sarina · 2024-11-06T20:15:22Z

docs/how-tos/create-new-filter.rst

@@ -196,7 +198,7 @@ Steps
        self.assertDictContainsSubset(attributes, exception.__dict__)

 .. note::
-    Basically, we're testing the filter's signature and the filter's behavior for stopping the process. The first test is testing the filter's signature, which is the set of parameters that the filter receives and returns. The second test is testing the filter's behavior for stopping the process, which is the exception that is raised when the filter stops the process.
+    Basically, we're testing the :term:`filter signature<Filter Signature>` and the filter's behavior for stopping the process. The first test is testing the :term:`filter signature<Filter Signature>`, which is the set of parameters that the filter receives and returns. The second test is testing the filter's behavior for stopping the process, which is the exception that is raised when the filter stops the process.


I think this could be explained a little better. But I may not get it right. Maybe,

Suggested change

Basically, we're testing the :term:`filter signature<Filter Signature>` and the filter's behavior for stopping the process. The first test is testing the :term:`filter signature<Filter Signature>`, which is the set of parameters that the filter receives and returns. The second test is testing the filter's behavior for stopping the process, which is the exception that is raised when the filter stops the process.

In this example, we're testing the :term:`filter signature<Filter Signature>` and the filter's behavior for stopping the process. The first test is testing the :term:`filter signature<Filter Signature>`, specifically that the behavior works as expected when passed mock form data. The second test is testing the filter's behavior for stopping the process, which is the exception that is raised when the filter stops the process.

I think the phrase " which is the set of parameters that the filter receives and returns" isn't needed, because we explain that in detail in the lines above the test.

felipemontoya

I think this glossary is correct. I was mostly looking at the content and did not review the format at all.

Left a minor comment from what looks like a missing word, nut otherwise good to merge

felipemontoya · 2024-11-13T18:19:05Z

docs/reference/glossary.rst

+     A pipeline step is a function within a pipeline that receives, processes, and returns data. Each step may perform operations like transforming, validating, filtering, or enriching data. Pipeline steps are implemented as classes that inherit from the base class `PipelineStep`_ and define specific logic within their `run_filter`_ method, which is executed by the pipeline tooling when the filter is triggered.
+
+   Filter Definition
+     A filter definition is a class that inherits from `OpenEdxPublicFilter`_ that implements the ``run_filter`` which defines the input and output behavior of the filter. This class executes the configured pipeline steps by calling the method `run_pipeline`_, passing down the input arguments, handling exceptions and returning the final output of the filter. Since the ``run_filter`` method is the entry point for the filter, the pipeline steps must have the same signature as the filter definition.


Suggested change

A filter definition is a class that inherits from `OpenEdxPublicFilter`_ that implements the ``run_filter`` which defines the input and output behavior of the filter. This class executes the configured pipeline steps by calling the method `run_pipeline`_, passing down the input arguments, handling exceptions and returning the final output of the filter. Since the ``run_filter`` method is the entry point for the filter, the pipeline steps must have the same signature as the filter definition.

A filter definition is a class that inherits from `OpenEdxPublicFilter`_ that implements the ``run_filter`` method which defines the input and output behavior of the filter. This class executes the configured pipeline steps by calling the method `run_pipeline`_, passing down the input arguments, handling exceptions and returning the final output of the filter. Since the ``run_filter`` method is the entry point for the filter, the pipeline steps must have the same signature as the filter definition.

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

mariajgrimaldi force-pushed the MJG/update-glossary-reference branch from a4d0873 to 7067589 Compare October 15, 2024 12:35

mariajgrimaldi changed the title ~~docs: use glossary as reference material~~ docs: [FC-0074] use glossary as reference material Oct 31, 2024

mariajgrimaldi added 4 commits November 4, 2024 14:00

docs: use glossary as reference material

be327ea

docs: use glossary directive

d8303e6

fix: add glossary to reference index

1712817

refactor: improve wording in glossary and reference it throughout docs

4a92546

mariajgrimaldi force-pushed the MJG/update-glossary-reference branch from 58c31d9 to 4a92546 Compare November 4, 2024 13:00

mariajgrimaldi added the FC Relates to an Axim Funded Contribution project label Nov 4, 2024

fix: fix indentation for glossary entries

d11e2c9

mariajgrimaldi force-pushed the MJG/update-glossary-reference branch from 22d1111 to d11e2c9 Compare November 4, 2024 13:10

fix: use glossary reference correctly

c7025e9

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

mariajgrimaldi requested a review from a team as a code owner November 4, 2024 13:17

mariajgrimaldi added 2 commits November 4, 2024 14:32

refactor: improve glossary description with usage for each component

ef3a9a0

refactor: drop note about calling the mechanism filter to avoid confu…

420cad0

…sion

mariajgrimaldi requested a review from sarina November 4, 2024 16:36

sarina reviewed Nov 4, 2024

View reviewed changes

refactor: address PR reviews

9be58a1

sarina approved these changes Nov 6, 2024

View reviewed changes

refactor: address PR reviews

0b70aa8

Ian2012 approved these changes Nov 12, 2024

View reviewed changes

felipemontoya approved these changes Nov 13, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: [FC-0074] use glossary as reference material #221

docs: [FC-0074] use glossary as reference material #221

mariajgrimaldi commented Oct 15, 2024 •

edited

Loading

openedx-webhooks commented Oct 15, 2024 •

edited

Loading

mariajgrimaldi commented Nov 4, 2024

sarina Nov 4, 2024

mariajgrimaldi Nov 4, 2024

sarina Nov 6, 2024

sarina Nov 6, 2024

felipemontoya left a comment

felipemontoya Nov 13, 2024

docs: [FC-0074] use glossary as reference material #221

Are you sure you want to change the base?

docs: [FC-0074] use glossary as reference material #221

Conversation

mariajgrimaldi commented Oct 15, 2024 • edited Loading

Description

openedx-webhooks commented Oct 15, 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 Nov 4, 2024

sarina Nov 4, 2024

Choose a reason for hiding this comment

mariajgrimaldi Nov 4, 2024

Choose a reason for hiding this comment

sarina Nov 6, 2024

Choose a reason for hiding this comment

sarina Nov 6, 2024

Choose a reason for hiding this comment

felipemontoya left a comment

Choose a reason for hiding this comment

felipemontoya Nov 13, 2024

Choose a reason for hiding this comment

mariajgrimaldi commented Oct 15, 2024 •

edited

Loading

openedx-webhooks commented Oct 15, 2024 •

edited

Loading