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. 

Release notes are organized first by date and are cumulative, with the most recent date first.

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

For each release, the document has sections for the different edX products affected. Typically a section for an edX product (Studio, LMS, Insights) 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.

The release master for edx-platform generates a wiki page that lists every commit included in a release. The dated list of LMS/Studio Release Pages provides links to these pages. 

Resources

Delivery

The 1. Writing Release Notes page describes release notes goals, content, and delivery. It also contains a step-by-step description of the process by which the doc team has historically created release notes.

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 for each release on the edX partner portal and Open edX portal. The portals automatically send an email when the announcement is published (though the email may not arrive until several hours later).

For the mechanics of publishing the release notes and all guides affected by a release, and announcing the release, see:

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.

A portal announcement that summarizes the release notes, with email notification to subscribers, 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.

Update Documentation 

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

One documentation team member is responsible for writing the release notes each week. That writer works with the product managers to make sure that the included features and changes are described accurately and positioned appropriately.

For features released from other repos, the product managers and doc team members work together to decide on what will be included in the weekly release notes.

Tools

Release notes use the edX wiki, Sublime (or another text editor), GitHub, and ReadTheDocs.

The release portal announcement uses the partner and Open edX portals.

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.