Audience: Partner and Open edX course teams, Open edX system administrators, Open edX developers, researchers

Owner: Product team

For more information about release notes processes, see the following pages.

Introduction

Release notes provide regular information to partner institutions and the Open edX community, including course teams, system administrators, and developers, about the latest updates to the platform. Many users see release notes as the primary way to stay up to date on platform developments.

Release notes are meant for the entire edX community, but are most frequently used by partner course teams and Open edX users. MIT ODL in particular reviews the release notes in weekly release audit meetings. (For more information about the way MIT ODL uses release notes, see MIT's Release Notes Use Cases).

In addition to posting the release notes at docs.edx.org, the documentation team publishes a portal announcement that abridges the release notes. The portal announcement is available on the partner and Open edX portals, and is also sent via e-mail to portal subscribers.

Content

Release notes are organized first by date, with the most recent date first. They are also organized by product.

For each release, the document has sections for the different edX products affected. Typically a section for an edX product (Studio, LMS, Insights, Open edX) contains information about new features or enhancements, issues with workarounds, and fixed bugs.

Where applicable, JIRA IDs are included for internal reference. For information about how to add JIRA references, see Cross-References to JIRA in the EdX Style Guide.

Delivery

The release notes are available as an HTML page through the Release Notes link on the docs.edx.org index page.

The doc team also publishes release announcements that summarize the release notes on the edX partner portal and Open edX portal. The announcement is made approximately two hours after the platform release. This time lag helps assure that a retraction is not needed in cases when the release must be reverted.The portals automatically send an email when the announcement is published (though the email may not arrive until several hours later).

The 1. Writing Release Notes page contains a step-by-step description of the process by which the doc team has historically created release notes.

Frequency

Release notes are produced to accompany each release of the edX platform. Publication of the release notes and all guides with release-related updates occurs as soon as feasible after the release "goes live on prod" (that is, it is in production on edx.org).

Changes made to other repos, including the edx-analytics-dashboard (Insights), the mobile apps, IDAs, and ORA2, are released on other schedules. Those changes are included in the next release notes, which might therefore follow the software release by a week or even more.

Update Documentation 

The process for creating or updating the release notes is outlined on the 1. Writing Release Notes page.

Tools

Release notes use the edX wiki, Sublime (or another text editor), GitHub, and ReadTheDocs. For more information, see 1. Writing Release Notes.

The release portal announcement uses the partner and Open edX portals. For more information, see 3. Publishing the Release Portal Announcement.

Open edX Releases

For Open edX releases beginning with Dogwood, the Open Source team is responsible for identifying all of the additions and changes to document in the release notes. This effort includes asking engineers to identify features and updates that have an impact on the next named release on a wiki page, and going through release notes written for edX platform releases since the last named release to identify what to include. This work for named releases can also uncover changes that have not yet been documented. 

One writer is responsible for assembling and completing the release notes. The Open Source team works with the writer to identify and provide source material and expertise for migrations, configuration changes, etc. needed for the upgrade.