docs(sharing): badges and verifiable credentials documentation rework by GlugovGrGlib · Pull Request #2968 · openedx/credentials

GlugovGrGlib · 2026-03-11T13:59:09Z

Description

A major revamp of developer's and operator's documentation related to credentials sharing and implementations of the badging and verifiable credentials.

Some notable changes include:

Reorganize the badges and verifiable credentials docs under a new docs/sharing/ parent directory.
Move infrastructure topics below user-facing features for better discoverability in docs/index.rst toctree.
Expand badges and verifiable credentials documentation with new pages for configuration and technical references.
Add C4 architecture diagrams and VC lifecycle diagram.
Update README with improved project description.

Testing instructions

See the latest docs build at https://docsopenedxorg--2968.org.readthedocs.build/projects/edx-credentials/en/2968/

openedx-webhooks · 2026-03-11T13:59:15Z

Thanks for the pull request, @GlugovGrGlib!

This repository is currently maintained by @2U-aperture.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are 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.

Details

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.

sarina · 2026-03-31T14:02:53Z

I think the PR description might be incorrect - for docs PRs, it's often nice to link to all the changed pages within the build. But no need to do that I'm already trying to find them.

sarina

This is a really huge PR. I spent over an hour with it and only got halfway through. I will try to find more time soon to finish.

sarina · 2026-03-31T14:13:00Z

docs/_diagrams/sharing/credential_sharing.dsl

+        openedX = softwareSystem "Open edX" {
+            edxPlatform = container "openedx-platform" "LMS and course management" "Python/Django"
+            eventBus = container "Event Bus" "Redis Streams or Kafka" "" "Queue"
+            credentialsService = container "edX Credentials" "Stores learner achievements, issues credentials" "Python/Django" {


Can we call the service "Open edX Credentials", or is there a reason it needs to be "edX Credentials"?

sarina · 2026-03-31T14:14:42Z

docs/_diagrams/sharing/credential_sharing.dsl

+            }
+            element "Software System" {
+                background "#1168bd"
+                color "#ffffff"


[suggestion] these diagrams rely heavily on shades of blue, which may not be very accessible. Further, black on light blue probably doesn't pass accessible contrast ratios.

sarina · 2026-03-31T14:17:15Z

docs/sharing/badges/configuration/accredible.rst

+-----------------------------
+
+Multiple Accredible API Configurations can be configured.
+All communication between Open edX Credentials and Accredible happens on behalf of an Accredible API config.


Suggested change

All communication between Open edX Credentials and Accredible happens on behalf of an Accredible API config.

All communication between Open edX Credentials and Accredible happens on behalf of an Accredible API configuration within the Open edX platform.

sarina · 2026-03-31T14:17:30Z

docs/sharing/badges/configuration/accredible.rst

+Multiple Accredible API Configurations can be configured.
+All communication between Open edX Credentials and Accredible happens on behalf of an Accredible API config.
+
+Go to the Accredible API Configs section in the admin panel and create a new item:


Suggested change

Go to the Accredible API Configs section in the admin panel and create a new item:

Go to the Accredible API Configs section in your instance's admin panel and create a new item:

sarina · 2026-03-31T14:18:14Z

docs/sharing/badges/configuration/accredible.rst

+Synchronization
+~~~~~~~~~~~~~~~
+
+To synchronize Accredible groups for an API Configuration:


Why do I need to do this? When do I need to do this?

sarina · 2026-03-31T14:43:39Z

docs/sharing/badges/index.rst

+
+**Data rule**
+   A filter on a requirement's event payload
+   (e.g. ``course.course_key equals course-v1:edX+DemoX``).


When we're giving an example of a course key can we use course-v1:OpenedX+DemoX+Demo_Course since that's the way the course key is expressed in https://github.com/openedx/openedx-demo-course/blob/master/demo-course/course/course.xml (which is the demo course you can load into your Open edX instance)

sarina · 2026-03-31T14:45:13Z

docs/sharing/badges/management.rst

+
+For **Credly**:
+
+#. Select one or more organizations on the "Credly Organizations" list page.


Is there Credly docs we can point to here?

sarina · 2026-03-31T14:45:20Z

docs/sharing/badges/management.rst

+
+For **Accredible**:
+
+#. Select one or more configurations on the "Accredible API Configs" list


Is there Accredible docs we can point to here?

sarina · 2026-03-31T14:46:19Z

docs/sharing/badges/management.rst

+
+.. note::
+
+    Each badge is an extended version of a user credential record.


I don't understand what this means or why it needs to be in a callout box

sarina · 2026-03-31T14:49:02Z

docs/sharing/badges/management.rst

+-------------------------
+
+Deactivate a badge template by unchecking the ``is active`` checkbox
+on its edit page. See :ref:`badges-configuration` for activation details.


Could you provide a reflink to the actual "Activation" section on this page?

Also probably worth noting (a) that you need to also Save the configuration when unchecking the is_active checkbox, and (b) what the consequences of doing this are (eg, are badges revoked or retained? Are there any side effects?)

Also why doesn't the https://docsopenedxorg--2968.org.readthedocs.build/projects/edx-credentials/en/2968/sharing/badges/configuration/index.html#activation section also describe disabling it? Seems weird that the Activation instructions aren't coupled with Deactivation instructions.

GlugovGrGlib · 2026-03-31T16:30:29Z

@sarina You're right about the description, this comes from the default PR template. I'll update it shortly.
Thanks for the review and suggestions. Please, take your time to finish it. I'll start working on fixes meanwhile for what has already been mentioned, but I won't push updates until you finish this pass to not disrupt you.

GlugovGrGlib added 3 commits March 11, 2026 14:58

docs: update readme and fix typos in credentials sharing docs

f18a792

docs(vc): move credentials sharing docs under the same parent dir

14c281f

docs: major docs refresh and improvement

75e1fe5

github-project-automation bot added this to Aperture-Maintained Mar 11, 2026

openedx-webhooks added open-source-contribution PR author is not from Axim or 2U core contributor PR author is a Core Contributor (who may or may not have write access to this repo). labels Mar 11, 2026

openedx-webhooks added this to Contributions Mar 11, 2026

github-project-automation bot moved this to Needs Triage in Contributions Mar 11, 2026

mphilbrick211 moved this from Needs Triage to Waiting on Author in Contributions Mar 11, 2026

GlugovGrGlib added 2 commits March 19, 2026 22:29

docs: finalize c4 diagrams and text enhancements

3073c73

docs: major update and docs polishing for credentials sharing

19e7d56

GlugovGrGlib changed the title ~~docs(sharing): badges and verifiable credentials documentation update~~ docs(sharing): badges and verifiable credentials documentation rework Mar 25, 2026

GlugovGrGlib requested a review from sarina March 25, 2026 13:54

GlugovGrGlib marked this pull request as ready for review March 25, 2026 14:00

sarina reviewed Mar 31, 2026

View reviewed changes

GlugovGrGlib self-assigned this Mar 31, 2026

	All communication between Open edX Credentials and Accredible happens on behalf of an Accredible API config.
	All communication between Open edX Credentials and Accredible happens on behalf of an Accredible API configuration within the Open edX platform.

	Go to the Accredible API Configs section in the admin panel and create a new item:
	Go to the Accredible API Configs section in your instance's admin panel and create a new item:


		For Credly:

		#. Select one or more organizations on the "Credly Organizations" list page.


		For Accredible:

		#. Select one or more configurations on the "Accredible API Configs" list


		.. note::

		Each badge is an extended version of a user credential record.

Conversation

GlugovGrGlib commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing instructions

Uh oh!

openedx-webhooks commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sarina commented Mar 31, 2026

Uh oh!

sarina left a comment

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!

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!

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!

GlugovGrGlib commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

GlugovGrGlib commented Mar 11, 2026 •

edited

Loading

openedx-webhooks commented Mar 11, 2026 •

edited

Loading

GlugovGrGlib commented Mar 31, 2026 •

edited

Loading