1. Writing Release Notes
Note: While the writer is writing the release notes, another member of the team tests the context-sensitive links in Studio and the LMS. For more information, see the following pages. |
---|
The process for creating or updating release notes is the process outlined on the Creating and Updating Documentation - RTD page, with the additional steps outlined below.
Note: The source files for edX release notes are in the edx-documentation/en-us/release_notes folder.
- Review the list of commits that are in the week's releases and works with the product team to determine which items are mentioned, and the descriptive text for each item.
- Create a branch in the edx-documentation repo, e.g. "RN_WeekEndFeb3" for easy identification.
- On this branch, create the rst source files for the release notes as follows:
- Identify what components are affected. For example, studio, lms, analytics, documentation.
- In the release_notes/2017 folder, in the appropriate component subfolders (create one if it doesn't yet exist), add a dated file where you'll write the item descriptions. For example, if there is a Studio item and an Analytics item, create studio_2017-02-03.rst under the "studio" subfolder and analytics_2017-02-03.rst under the "analytics" subfolder.
- In the release_notes/source/ folder, update the index file for each affected component. For example, update studio_index.rst with a title "Week ending 3 Feb 2017" and an "include" directive to the file you created in step b.
- In the release_notes/source/2017 folder, add a summary file for that week's releases, named for the release date (usually the Friday). For example, 2017/2017-02-03.rst. In this date summary file, add a title (e.g. "Studio" or "Analytics") and an "include" directive to each file you created in step b.
- In the 2017 folder, update the index.rst with an entry for the summary file you just created. Note that these lines are filenames, not dates.
- Commit your changes to your branch.
- On GitHub, create a pull request and tag reviewers. (Going to the repo in Github.com and creating the pull request there gets you the proper PR template).
- Development, Product, PM, and Training teams review and revise the release notes, making sure that the included features and changes are described accurately and positioned appropriately.
- Make revisions as necessary. Before merging the PR, squash commits.
- Merge the pull request.
- Build the release notes project on RTD.
- Update the release date on the docs.edx.org page.