Skip to content

fix: point help-token documentation links at docs.openedx.org "latest" - #39154

Open
uhlhosting wants to merge 3 commits into
openedx:masterfrom
uhlhosting:fix/help-urls-doc-version
Open

uhlhosting wants to merge 3 commits into
openedx:masterfrom
uhlhosting:fix/help-urls-doc-version

Conversation

@uhlhosting

Copy link
Copy Markdown

Description

On named release branches (e.g. release/verawood), openedx.core.release.doc_version() returns open-release-<line>.master, which is substituted into every help link via HELP_TOKENS_VERSION (openedx/envs/common.py). But docs.openedx.org does not publish versions under that slug — the Read the Docs project (docsopenedxorg) serves latest and, at most, bare release names like ulmo.

Result: every generated help link 404s on every named release. Example from a Verawood deployment — the "documentation" link inside Studio's Section Highlights dialog on the course outline points to:

https://docs.openedx.org/en/open-release-verawood.master/educators/how-tos/course_development/manage_course_highlight_emails.html  → 404

Correct URL: https://docs.openedx.org/en/latest/educators/how-tos/course_development/manage_course_highlight_emails.html (200).

This change makes doc_version() return "latest" unconditionally, so help links resolve on all release lines. It is a no-op on master (where it already returned "latest"); the value flows to HELP_TOKENS_VERSION (help-tokens resolution for CMS/LMS help links, get_help_urls() / /api/contentstore/v1/help_urls) and to the MFE config instructor support URL (resolve_help_token in mfe_config_api).

Impacted roles: Course Author (broken help links in Studio/MFEs), Learner (instructor-dashboard support link), Operator (reported broken links).

Supporting information

  • help-tokens is being deprecated precisely because its URL pattern no longer works with docs.openedx.org: Remove help-tokens (after LMS legacy frontends are removed) help-tokens#260
  • Verawood migrated HELP_TOKENS_BOOKS to docs.openedx.org/en/latest (release notes), which is what makes the /latest → /open-release-verawood.master substitution produce a dead URL on that branch.

Testing instructions

  1. On a named-release deployment, open any help link Studio generates via help-tokens — e.g. in Course Authoring, open a course outline → Section Highlights → the "documentation" link. Before: .../en/open-release-<line>.master/... (404). After: .../en/latest/... (200).
  2. GET /api/contentstore/v1/help_urls returns en/latest URLs for every token.
  3. Unit tests: doc_version() consumers derive expectations dynamically (mfe_config_api tests), nothing asserts the old slug format.

Deadline

None — but a backport to release/verawood would fix currently broken help links on the active release.

Other information

  • Alternative considered: return the bare RELEASE_LINE (RTD slug en/ulmo does exist). Rejected because en/verawood (and future lines) isn't published yet, so links stay broken for a while after each release cut; latest always resolves.
  • I did not find an existing issue for this; closest related context is the help-tokens deprecation noted above.

doc_version() returned "open-release-<line>.master" on named release
branches, but docs.openedx.org does not publish versions under that slug
(RTD serves "latest" and bare release names like "ulmo"). Every
generated help link — including the "documentation" link in the Studio
course-outline Section Highlights dialog — therefore 404s on release
lines. Always return "latest" so the links resolve.
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

@openedx-webhooks openedx-webhooks added the open-source-contribution PR author is not from Axim or 2U label Sep 25, 2026
@openedx-webhooks

Copy link
Copy Markdown

Thanks for the pull request, @uhlhosting!

This repository is currently maintained by @openedx/wg-maintenance-openedx-platform-oncall.

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
🔘 Submit a signed contributor agreement (CLA)

⚠️ We ask all contributors to the Open edX project to submit a signed contributor agreement or indicate their institutional affiliation.
Please see the CONTRIBUTING file for more information.

If you've signed an agreement in the past, you may need to re-sign.
See The New Home of the Open edX Codebase for details.

Once you've signed the CLA, please allow 1 business day for it to be processed.
After this time, you can re-run the CLA check by adding a comment below that you have signed it.
If the CLA check continues to fail, you can tag the @openedx/cla-problems team in a comment for further assistance.

🔘 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.

@mphilbrick211

Copy link
Copy Markdown

Hi @uhlhosting! Welcome, and thank you for this contribution! In order for your CLA check to turn green, you'll need to submit a CLA form. If you are contributing as an individual, please fill out the individual CLA form here.

If you are contributing on behalf of an organization, please have your manager reach out to oscm@axim.org so you may be added to your org's existing entity agreement.

Please let me know if you have any questions. Thanks!

@mphilbrick211 mphilbrick211 added the needs test run Author's first PR to this repository, awaiting test authorization from Axim label Sep 29, 2026
@uhlhosting

Copy link
Copy Markdown
Author

@mphilbrick211 Hi, I have just submitted my form for approval.

@mphilbrick211

Copy link
Copy Markdown

@mphilbrick211 Hi, I have just submitted my form for approval.

Hi @uhlhosting! Apologies for the delay as I was out of office last week.

Are you contributing on behalf of UHL Hosting? If so, we'll need to do a different kind of agreement since you would not be contributing as an individual. Could you please clarify for us? That way we can make sure we get the right form over to you. Thanks!

@mphilbrick211

Copy link
Copy Markdown

@mphilbrick211 Hi, I have just submitted my form for approval.

Hi @uhlhosting! Apologies for the delay as I was out of office last week.

Are you contributing on behalf of UHL Hosting? If so, we'll need to do a different kind of agreement since you would not be contributing as an individual. Could you please clarify for us? That way we can make sure we get the right form over to you. Thanks!

Hi @uhlhosting following up on my question above. Thanks!

@mphilbrick211 mphilbrick211 removed the needs test run Author's first PR to this repository, awaiting test authorization from Axim label Oct 27, 2026
@uhlhosting

Copy link
Copy Markdown
Author

Hi @mphilbrick211 I am developing in behalf of UHL Hosting. How should we proceed?

@mphilbrick211

Copy link
Copy Markdown

@uhlhosting thanks for confirming! I'm checking on this for you now. Will get back ASAP!

@e0d

e0d commented Nov 20, 2026

Copy link
Copy Markdown
Member

@uhlhosting I've merged the upstream changes into your branch, please update any checkouts you have.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

open-source-contribution PR author is not from Axim or 2U

Projects

Status: Needs Tests Run or CLA Signed

Development

Successfully merging this pull request may close these issues.

4 participants