Open edX Release Documentation and Versioning

Owned by Alison Hodges
Last updated: Dec 08, 2021 by Ned Batchelder (Deactivated)

For information used by your OSCM buddy to prepare a release candidate and release an Open edX release, see Process to Create an Open edX Release.

For background about the goals and history of Open edX documentation, see /wiki/spaces/DOC/pages/30966139.

Preparing Open edX Release Documentation

Ongoing Doc Team process

As features are added that also add feature flags, change default settings, require upgrades, and otherwise might make change of interest to Open edX sites but not typically surfaced in the weekly release notes, doc team members should add individual DOC tasks and associate them with the release epic, or label with the release name.

Writing process

1. On or before the day the first release candidate (RC) is cut, get your house in order.

  • Major new features in an Open edX release can be identified from the weekly release notes prepared for the time period from the last release date through the date the first release candidate (RC) is cut.
  • You can also produce a report of all DOC stories with a label = the release's name.
  • In addition, the engineering teams maintain a wiki page of changes that will be included in the release (for example, this page for the Eucalyptus release).

2. Verify that the latest versions of all Open edX guides are up to date with all of the changes you've been able to identify for the release, including feature doc for all audiences, feature flags, deployment issues... everything. Search for references throughout the edx-doc repo to the old releasename, revise or replace as needed.

3. Your OSCM buddy will create a release-name branch off of master in the edx-documentation repo (for example, open-release/zebrawood.master). This is the branch that release-specific guides get built from.

  • Make a branch off of this branch.
  • Add the release name to the titles of the the Open edX B&R, ICR, and Open edX Learner's guides: for each one, change the conf.py project name and the index.rst header
  • Make a PR, merge into the release-name branch.
  • This should be it for the B&R, ICR, and Learner's guides.
  • The release-name branch will remain open.

3a. Your OSCM buddy will also create a release-name branch off of master in the edx-platform repo.

  • Make a branch off of this branch.
  • Add the release name to the title of the the Platform API guide: change the conf.py project name and the index.rst header
  • Make a PR, merge into the release-name branch.
  • This should be it for the platform API guide.
  • The release-name branch will remain open.

Here's a PR with an example of what to do for 3 & 3a: https://github.com/edx/edx-documentation/pull/1197

4. Create a branch off of master for the Open edX release notes in the edx-documentation repo.

  • Set up a new releasename.rst file for the open edX release notes.
  • Revise the introduction to the open edX release notes.
  • Merge PRs and close the branch.

5. Nothing should need to change in the open-release branch in edx-platform, but that is new, so double-check :)

RTD process

In RTD, versions for an Open edX release are created from a protected GitHub branch. After the release-name branch is built, you can find a corresponding version in RTD on the Versions page, in the long list of inactive versions. Find the release-name branch version, click Edit, and select Active.

  • We should consider the release version frozen and only update it separately from master in extreme circumstances.
  • Ned and Alison found that it makes sense to specify the RTD version as the GitHub branch, and make any necessary doc changes to a PR on the release-name.rc branch.
  • There is a (slow) automated process on RTD that updates the list of versions that you can make available for a project (Admin > Versions). Ned had to force this list to update by making "nedbump" PRs.

List of Guides Supporting a Release

Open edX documentation that supports a release of Open edX consists of the following guides.

  • Open edX Release Notes
    • Built off of master branch; uses latest project in RTD.
    • Each version is cumulative.
  • Installing, Configuring, and Running the edX Platform
    • Built off of release-name branch; uses release-name version in RTD.
    • For the Dogwood release, an RTD limitation required a shorter URL length. The Open edX ICR project, built from the named-release-dogwood.rc version, is the Dogwood version. RTD reports that this issue has been resolved, but we have not tested as of 25-Feb-2016.
  • Building and Running an Open edX Course
    • Built off of release-name branch; uses release-name version in RTD. 
    • For the Dogwood release, an RTD limitation required a shorter URL length. The Open edX CA project, built from the named-release-dogwood.rc version, is the Dogwood version. RTD reports that this issue has been resolved, but we have not tested as of 25-Feb-2016

For reference, the following guides for the Open edX community are not release-specific. They are always built off of master branch and use latest project in RTD.

  • edX Developer's Guide
  • XBlock Guide
  • edX Open Learning XML Guide - Alpha

Going forward, we will evaluate the need to provide separate Open edX Insights documentation, including its on-line help.

End-User Impact

Open edX Users can access documentation in the following ways. Below each way is a description of what we need to do to fully enable users.

  • docs.edx.org
  • Studio online help
    • Currently Studio online help for all users links to Partner course staff documentation.
    • We will change online help configuration to:
      • By default point to the latest Open edX documentation.
      • Modify the configuration in release branches to point to the release-specific version of documentation.
      • Work with Devops to enable changing configuration in edx.org and Edge deployments to point to Partner documentation.
  • LMS online help (two links from the Instructor Dashboard) - leads to Zendesk Help Center
  • Search Engines
    • As we support more versions of documentation, search engines can return multiple versions of the same content.
    • We will update titles and chrome around documents to make the audience and version more clear.

Remaining Tasks.

Add information to the Preface for Open edX to show how to get different versions from within an RTD document. WILL NOT DO.

  • Work with Devops to update config.ini file in Platform to point to latest Open edX guide, but be modified during deployment to edx.org and Edge to point to the Partner version.
  • Work with Zach to move Saudi to Open edX doc links so we can eventually close Doroob projects.