Hooks: Events and Filters (Phase 3)

[e0d]

There is still some hooks related work in-flight right now, so the timeline to start really hammering out the next phase of this work would be around mid-January. THIS IS VERY MUCH A DRAFT ITEM AT THIS POINT.

That next phase should include at least:

• Automated documentation generation
• Adjustments/fixes based on developer feedback, if any.

Other items that could go into this phase, but may also be pushed off if we're not ready:

• New events/filters? (need details)
• Message queue integration (this will depend on the state of Arch-BOM's message queue related work).
• Moving openedx-events and openedx-filters into the openedx org (with the current set of eduNEXT developers maintaining commit rights, of course). This may be punted just because we don't yet have an established criterion for when things live in the openedx org vs. elsewhere, but I (@ormsbee) personally support this framework becoming central enough to the platform to justify being in the openedx org.

[ormsbee]

Assigning to myself for better definition.

[sarina]

@mariajgrmaldi said in the CC meetup on Tuesday that things around events & filters felt pretty finalized.

Maria, where are you at with the project? What of the things listed in this ticket are still incomplete, or require tCRIL to be involved?

[ormsbee]

@mariajgrmaldi, @felipemontoya: I'm particularly interested in your thoughts around improving documentation for events and filters, as they're going to be two of the primary extension mechanisms we point people to.

[felipemontoya]

I think that what we have lately refer to as finalized is a state where events and filters where in master, backported to nutmeg (some part that we did not manage to deliver before the cut) and overall usable. That was the initial scope that we set as our goal. Also since this was initially partially funded by a blended project we needed to put the finish line somewhere.

Now that this is all done, there is plenty of work to be done to actually make this the primary extension mechanism. I think the most critical areas are:

• documentation: we wrote a static list of the things that we were including here, but this list needs to be auto-generated and connect to docs.openedx.org. I remember that Maria investigated some work that could be done on creating an event type for the toggles library that does the docs extraction.

• adoption: so far there have been some attempts by people outside of the project to get involved. Mostly by opencraft. I think we need to get some features built on top of hooks. At some point I thought we could go and refactor bits of enterprise code or certificates to try to get 2u in the mix. It does not have to be in those areas of the code. But we do need to get some more examples of feature built on top of this.

• more events/filters: we built what we thought was a representative array of interesting events/filters for different use cases. However there are still many hooks waiting to be written. I think this connects with the issue of adoption.

• the stable APIs affair: the moment that hooks start to be broadly used, there will be many extension writers that will encounter the banana/jungle problem on the other end of the chain. The plugins will need to import code from edx-platform to perform some meaningful work. Maybe that ends up being a lot of api.py modules from oep-49 or openedx-learning. I think that will be the next bottleneck.

[sarina]

Also we didn't tag @mariajgrimaldi properly 😓

[mariajgrimaldi]

Hello! Sorry for not specifying what we've exactly finalized here 😅

Now, I agree that there's much more to do for hooks to be the primary extension strategy. I'm currently trying to improve a pain point for adopters, as Dave said, documentation. This is what I have in mind on doing:

• How-tos for each library. I'm currently working on a how-to for openedx-events
• Resolve: how to unify or reference the documentation on edx-platform + openedx-events + openedx-filters? Here I'll need some help since we have a guide on edx-platform, but the rest of the documentation is on each repo. Which practice should we adopt here? (depending on this answer, we could decide what to do with the docs auto-generation)
• What else should we consider? 🤔

Also, I've been thinking of adding a list of proposed filters/events in each project's repo I created to keep track of our roadmap, but if I'm honest, this hasn't been my priority 😅

[sarina]

@feanil - do you have any words of wisdom to impart to @mariajgrimaldi around the documentation needs for events & filters?

[feanil]

@mariajgrimaldi I think we can use the new root doc site to help unify the documentation. I think guides for how to use openedx events and filters should probably go into the events or filters repo but it sounds like there is also a catalog of events/filters that will be specific to each service and would live in the repo for that service is that right? I'd be happy to help figure out a good organization for this.

[mariajgrimaldi]

@feanil: yes, that's right.

There are a few sections in the docs explaining how to use and test & also some live examples. There are also, as you said, two indexes, one for Open edX Events and one for Open edX Filters.

So we could move the indexes to the root docs and link there to each repo documentation. Most code examples in the current doc are related to the LMS, but could we standardize them to be more agnostic to add them to each repository? Or could we use those code examples in the root docs? 🤔

Let me know how we can get started on this.

[feanil]

We can definitely use the edx-platform examples in the root doc. Here is one example layout I could imagine for docs in openedx-events

└── openedx-events
    └── docs
        ├── concepts
        │   └── event-architecture.rst
        ├── decisions
        ├── how-tos
        │   ├── adding-new-events.rst
        │   ├── adding-openedx-events-to-a-new-service.rst
        │   ├── configure-openedx-events-with-edx-platform.rst
        │   └── using-openedx-events-with-edx-platform.rst
        ├── quickstarts
        │   └── using-events-to-call-a-webhook-on-enrollments.rst
        └── references

            └── index.rst  # This would have links to all the list of events in different repos.

Does that help with things might go where? I think the app repos that use openedx-events should just document what events they have and then cross link back to the openedx-events repo for any docs on installing, configuring, etc.

[mariajgrimaldi]

That's great; thanks for the suggestion! That will work for the info we currently have & it will make it easier to add more later.
😄
I'll rearrange what we have following that layout.