1. Writing Release Notes

Goal

Provide "what's new" documentation with each weekly release on Edge and edX.org that clearly presents user-facing changes and workarounds to any new issues.

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

Currently there is a single document primarily for course staff, though some community developer and researcher information is included.

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:

A list of new features or enhancements
A list of issues with workarounds
A list of 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 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:

For information about creating content on the partner and Open edX portals, contact a member of the doc team. To create an account on the partner portal, see Kate Venier in Ed Services.

Identifying JIRA issues for Release Notes

Currently we rely on the LMS/Studio Release Pages wiki page and scrum masters directly for JIRA IDs that are resolved and committed in the release. We want to pursue a more automated way to manage this information, such as getting IDs from all the GitHub commits in the release.

For a head start before the Release engineering wiki is available, you can review the commits that have been made since the last release candidate was merged to master.

Reviewing Release Notes

Everyone across Development, Product, PM, and Training teams is encouraged to review release notes.

Development and product leads for large changes going into the release should be sure to review relevant sections.

Process Outline

The Documentation team drafts the release notes by making a new branch off of master. Development, product, and PMs review and revise the notes as necessary through a GitHub pull request.

Doc team creates a draft of release notes. The team also adds the file on the index.rst page.
When the draft is as complete as possible, create a pull request and tag Development, Product, and PM team members, asking for review and collaboration.
Development, Product, and PM teams can comment or make updates as necessary.
Doc team drafts an announcement for the partner and Open edX portals for review by another doc team member. The portal announcement is an abridged version of the release notes.
Doc team merges the pull request. If changes come in after this point, the team will make every effort to get the change published as soon as possible.
Doc team publishes the release notes and republishes all documents affected by the release by creating new builds of documentation projects on readthedocs.
Doc team updates the release date on the docs.edx.org page and publishes the portal announcement on the partner and Open edX portals. The portals automatically send the announcement to subscribers as an email message.

Information on hotfixes will be rolled into the next version of release notes. If a hotfix is critical to include in release notes immediately, or for other urgent changes, email docs@edx.org.