docs: [FC-0074] document contribution process to the hooks extension framework #640
Conversation
|
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. |
openedx-webhooks
added
the
open-source-contribution
mariajgrimaldi
changed the title
| @@ -163,6 +163,37 @@ Filters are useful when you need an immediate response that directly modifies th | |||
|
|
|||
| We encourage you to review the list of use cases for events and filters to draw inspiration from real-life scenarios and see if your use case aligns with any of them. Also, maybe your feature can be implementing using the framework but there's not an available event or filter for it yet. In that case, consider proposing a new event or filter to the community! | |||
|
|
|||
| What's Next? | |||
There was a problem hiding this comment.
I'm still thinking this is missing something. I'll re-review it tomorrow so I can open it for others to review.
There was a problem hiding this comment.
I think the high-level overview of the contribution process to the framework is good as it is.
mariajgrimaldi
force-pushed
the
MJG/contribution-workflow
branch
4 times, most recently
from
22514dd to
1391027
Compare
| What's Next? | ||
| ============ | ||
|
|
||
| Contribute to the Hooks Extension Framework |
There was a problem hiding this comment.
I think I would not nest this in a "What's Next" - I would just have this be its own second-level header so it shows up in the sidebar (so with **** below)
| Contribute to the Hooks Extension Framework | ||
| ------------------------------------------- | ||
|
|
||
| Before considering contributing to the framework, we suggest you make a quick proposal with your use case and intended solution, and share it with the community to gather feedback and validate the approach. This can be done in the Open edX Slack channels, the Open edX Discuss forum or in each repository's issue tracker. |
There was a problem hiding this comment.
I don't think I'd recommend making a proposal in Slack - proposals in the forum or issue tracker are better.
| #. For implementing the hook, follow the instructions in the guide specific to each repository for :doc:`openedx-events:how-tos/creating-new-events` and :doc:`openedx-filters:how-tos/create-new-filter`. | ||
| #. For integrating the hook into a service, follow the instructions in the relevant repository for :doc:`openedx-events:how-tos/using-events` and :doc:`openedx-filters:how-tos/using-filters`. | ||
| #. We recommend validating the previous steps simultaneously to ensure the implementations in both the hooks repository and the service align properly. The validation process might also include the implementation of an extension, e.g., a plugin, that uses the new hook to ensure it works as expected. | ||
| #. Once you've validated both implementations, you can open the Pull Requests for review. Typically, the Pull Request for the hook definition (in `openedx-events`_ or `openedx-filters`_) is opened first, along with a simultaneous PR in the service. While managing two Pull Requests at the same time might be challenging, it's recommended to avoid rework by validating definitions early, like ensuring the filter arguments are objects available during execution, verifying the event payload can be populated with the available information or that the hook name fits the context where it will be used, etc. |
There was a problem hiding this comment.
| #. Once you've validated both implementations, you can open the Pull Requests for review. Typically, the Pull Request for the hook definition (in `openedx-events`_ or `openedx-filters`_) is opened first, along with a simultaneous PR in the service. While managing two Pull Requests at the same time might be challenging, it's recommended to avoid rework by validating definitions early, like ensuring the filter arguments are objects available during execution, verifying the event payload can be populated with the available information or that the hook name fits the context where it will be used, etc. | |
| #. Once you've validated both implementations, you can open the Pull Requests for review. Typically, the Pull Request for the hook definition (in `openedx-events`_ or `openedx-filters`_) is opened first, along with a simultaneous PR in the service. While managing two Pull Requests at the same time might be challenging, it's recommended to avoid rework by validating definitions early, like ensuring the filter arguments are objects available during execution, verifying the event payload can be populated with the available information, that the hook name fits the context where it will be used, etc. |
Readability suggestion
There was a problem hiding this comment.
Hi @mariajgrimaldi, this looks good! The instructions for the contribution process are quite clear and detailed. I only have a little comment.
|
|
||
| Before considering contributing to the framework, we suggest you make a quick proposal with your use case and intended solution, and share it with the community to gather feedback and validate the approach. This can be done in the Open edX Slack channels, the Open edX Discuss forum or in each repository's issue tracker. | ||
|
|
||
| If you're new to contributing to the Hooks Extension Framework, we recommend also reading the :doc:`openedx-events:index` and :doc:`openedx-filters:index` documentation to understand each hook concepts and how to use them in your project. |
There was a problem hiding this comment.
In some places, the default link text I think is not the best, for example:
This would look better:
mariajgrimaldi
force-pushed
the
MJG/contribution-workflow
branch
from
a461362 to
2ca4f59
Compare
Description
This PR adds an overview of the frameworks contribution process from conception to contribution. The conception section is repo-specific, so it'd later on written as part of the "How To Create A(n) Event/Filter" for each repository, as for now, we're using the available documentation.