Document the various integration points for platform extensions by bradenmacdonald · Pull Request #24057 · openedx/openedx-platform

bradenmacdonald · 2020-05-22T23:31:19Z

As far as I know, we're missing a comprehensive guide to all the different ways that plugins or applications can integrate with Open edX. Here's my attempt to fix that :)

Now that we have Automatic notifications of ADR changes, my thought is that we can use the ADR watcher bot to watch this document as well, so that anyone who has asked to be notified of architectural decisions will get pinged when someone opens a PR that proposes a new extension point (provided their PR includes a change to this doc file).

Open question: is https://github.com/edx/edx-platform/blob/master/docs/guides/index.rst published somewhere in compiled form? It contains Sphinx directives that GitHub doesn't render, but I couldn't find a compiled version of it. If we're just using GitHub to view it (which I think is great), we should probably drop the toctree etc.

openedx-webhooks · 2020-05-22T23:31:30Z

Thanks for the pull request, @bradenmacdonald! I've created OSPR-4580 to keep track of it in JIRA. JIRA is a place for product owners to prioritize feature reviews by the engineering development teams.

Feel free to add as much of the following information to the ticket:

supporting documentation
edx-code email threads
timeline information ("this must be merged by XX date", and why that is)
partner information ("this is a course on edx.org")
any other information that can help Product understand the context for the PR

All technical communication about the code itself will still be done via the GitHub pull request interface. As a reminder, our process documentation is here.

nedbat · 2020-05-26T20:19:51Z

The ADR bot didn't send a notification about this. It isn't watching docs/*.rst: https://github.com/edx/pr_watcher_configuration/blob/master/config.yml#L4-L9

  patterns:
    - "decisions/*.rst"
    - "decisions/*.md"
    - "*/decisions/*.rst"
    - "*/decisions/*.md"
    - "oeps/*.rst"
    - "oeps/*.md"

pomegranited

@bradenmacdonald Thank you for this! Left some nits, but that's it.

FYI, if you could hold off addressing these nits until openedx/pr_watcher_configuration#12 is merged and deployed, then we can test that the ADR alerts happen as expected.

pomegranited · 2020-05-27T07:26:27Z

+|                     |                                          | contexts. However, Blockstore-based content libraries are.  |
+|                     |                                          | See |learning_context.py|_ to learn more.                   |
+---------------------+------------------------------------------+-------------------------------------------------------------+
+| User partition      | ``openedx.user_partition_scheme`` and    | A user partition scheme is a named way for dividing users   |


Oo cool, I didn't know about this one!

natabene · 2020-05-28T02:01:39Z

@bradenmacdonald Thank you for your contribution. @nasthagiri Will you review this?

bradenmacdonald · 2020-05-28T16:12:57Z

@nedbat

The ADR bot didn't send a notification about this. It isn't watching docs/*.rst: https://github.com/edx/pr_watcher_configuration/blob/master/config.yml#L4-L9

Right, I should have mentioned that I was going to open a PR to address that after this one had been reviewed, but now @pomegranited has done that for me - thanks :)

nasthagiri · 2020-06-03T02:00:41Z

@natabene @bradenmacdonald Reviewing this PR is now at the top of my backlog. I will prioritize this tomorrow. Thanks!

nasthagiri · 2020-06-03T12:24:01Z

@@ -0,0 +1,165 @@
+Options for Extending the edX Platform


@bradenmacdonald Thank you for taking the time to put this together.

@nasthagiri Thanks for the quick and helpful review! I've addressed all your comments.

nasthagiri · 2020-06-03T12:29:48Z

+.. contents:: **Integration Methods Overview**
+
+
+REST API Integration with External Applications


Can we add something like Support Level to each of these?

While the xBlock and Django App Plugin interfaces are intended for versioned support, we have yet to invest that time on our REST APIs. By listing it in this doc (and also as the 1st item), I am concerned folks will expect them to be stable APIs. At this time, only a few of our REST APIs are expected to be versioned and maintained for compatibility. Once we invest in standardizing our API practices (listed in Needed Architecture Investments), we will have a better foundation to support more stable REST APIs.

Can we add something like Support Level to each of these?

Once again, perhaps a field or some-such to indicate Support level would be useful.
In Tech Radar speak, we have the following categories: Adopt, Trial (or Invest), Assess, and Hold. See their definitions in this glossary. I believe a similar rating for each of the extensions in this doc would be useful to let people know the support level of its usage.

Sure, in my latest commit, I've proposed a new Status (Adoption and Completion) scheme, and added my best guess for each one. Please take a look!

nasthagiri · 2020-06-03T14:34:09Z

+.. |UserPartition docstring| replace:: ``UserPartition`` docstring
+.. _UserPartition docstring: https://github.com/edx/edx-platform/blob/f8cc58618a39c9f7b8e9e1001eb2d7a10395797e/common/lib/xmodule/xmodule/partitions/partitions.py#L105-L120
+
+Platform Look & Feel


@davidjoy FYI on this section

nedbat · 2020-06-04T18:16:28Z

I've taken Nimisha's suggestion, and added "guides" as a directory the bot watches.

edx-status-bot · 2020-06-05T19:55:57Z

Your PR has finished running tests. There were no failures.

nasthagiri

This looks great @bradenmacdonald!

Thanks for adding the status (adoption and completion) values. I'm hoping those will clarify our recommendations for folks.

I'll go ahead and squash before merging.

openedx-webhooks · 2020-06-10T21:22:36Z

@bradenmacdonald 🎉 Your pull request was merged!

Please take a moment to answer a two question survey so we can improve your experience in the future.

edx-pipeline-bot · 2020-06-11T00:49:07Z

EdX Release Notice: This PR has been deployed to the staging environment in preparation for a release to production.

edx-pipeline-bot · 2020-06-11T01:09:19Z

EdX Release Notice: This PR may have caused e2e tests to fail on Stage. If you're a member of the edX org, please visit #e2e-troubleshooting on Slack to help diagnose the cause of these failures. Otherwise, it is the reviewer's responsibility. E2E tests have failed. https://gocd.tools.edx.org/go/tab/pipeline/history/deploy_to_stage

edx-pipeline-bot · 2020-06-11T15:20:30Z

EdX Release Notice: This PR has been deployed to the production environment.

robrap · 2020-08-04T21:29:18Z

+     - A "Django app plugin" is a self-contained Django `Application`_ that can define models (MySQL tables), new REST APIs, signal listeners, asynchronous tasks, and more. Even some parts of the core platform are implemented as Django app plugins, for better separation of concerns (``announcements``, ``credentials``, ``grades``, etc.) Read the `Django app plugin documentation`_ to learn more.
+
+       Plugins can also inject custom data into django template contexts, to affect standard pages delivered by the core platform. See `Plugin Contexts`_ to learn more.


FYI: We are in process of moving this to edx-django-utils. See openedx/edx-django-utils#48

FYI: We are in process of moving this to edx-django-utils. See openedx/edx-django-utils#48

OK, cool. Could you please update this doc at the same time, to point to that new home for the functionality?

Oops. I thought this hadn't landed yet because I got a 404 on: https://github.com/open-craft/edx-platform/blob/master/docs/guides/extension_points.rst
I didn't realize I was searching in the wrong org. We can update the following accordingly:
https://github.com/edx/edx-platform/blob/master/docs/guides/extension_points.rst
Thanks.

Document the various integration points for platform extensions

6ad45ec

openedx-webhooks added needs triage open-source-contribution PR author is not from Axim or 2U labels May 22, 2020

bradenmacdonald requested a review from nasthagiri May 22, 2020 23:32

This was referenced May 22, 2020

[BB-933] Allow overriding xblock icons with plugins #21433

Merged

[BB-1674] Template plugins #21968

Closed

pomegranited mentioned this pull request May 27, 2020

Adds watcher for all docs rst and md files openedx/pr_watcher_configuration#12

Closed

1 task

pomegranited approved these changes May 27, 2020

View reviewed changes

openedx-webhooks added awaiting prioritization and removed needs triage labels May 28, 2020

Address minor review comments

4417cf4

nasthagiri reviewed Jun 3, 2020

View reviewed changes

Address Nimisha's review

18129d3

nasthagiri approved these changes Jun 10, 2020

View reviewed changes

nasthagiri merged commit 831a90e into openedx:master Jun 10, 2020

bradenmacdonald deleted the extension-points-doc branch June 11, 2020 00:41

robrap reviewed Aug 4, 2020

View reviewed changes

openedx-webhooks added merged and removed awaiting prioritization labels Jan 21, 2021

		.. contents:: Integration Methods Overview


		REST API Integration with External Applications

		- A "Django app plugin" is a self-contained Django `Application`_ that can define models (MySQL tables), new REST APIs, signal listeners, asynchronous tasks, and more. Even some parts of the core platform are implemented as Django app plugins, for better separation of concerns (``announcements``, ``credentials``, ``grades``, etc.) Read the `Django app plugin documentation`_ to learn more.

		Plugins can also inject custom data into django template contexts, to affect standard pages delivered by the core platform. See `Plugin Contexts`_ to learn more.

Uh oh!

Conversation

bradenmacdonald commented May 22, 2020

Uh oh!

openedx-webhooks commented May 22, 2020

Uh oh!

nedbat commented May 26, 2020

Uh oh!

pomegranited left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

natabene commented May 28, 2020

Uh oh!

bradenmacdonald commented May 28, 2020

Uh oh!

nasthagiri commented Jun 3, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nedbat commented Jun 4, 2020

Uh oh!

edx-status-bot commented Jun 5, 2020

Uh oh!

nasthagiri left a comment

Choose a reason for hiding this comment

Uh oh!

openedx-webhooks commented Jun 10, 2020

Uh oh!

edx-pipeline-bot commented Jun 11, 2020

Uh oh!

edx-pipeline-bot commented Jun 11, 2020

Uh oh!

edx-pipeline-bot commented Jun 11, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants