Working with the Presto release notes PR

What is in this document

This document describes how to work with the release notes PR to move it from a created state to merged. Much of this document explains how to consistently apply the Release Notes Guidelines to the programmatically gathered release note entries originally drafted by the PR authors, and format the gathered release notes for publication.

Anyone working with the release notes PR should be familiar with and refer to the Release Notes Guidelines while doing this work.

Overview

As part of the Presto release cycle, a PR is automatically created to generate the release notes page for that release in the Presto documentation. The release notes from each PR in the release are programmatically gathered and a draft page is generated as part of the release notes PR. An example of a release notes PR is the PR for the 0.293 release.

Note: The release notes PR blocks the Presto release cycle until it is merged, so prioritize work on the release notes PR if you are involved.

After the release notes PR is reviewed, approved, and merged, the Presto documentation for the new release is generated including this new page. The release notes published from the example PR are in the Presto documentation as Release 0.293.

Make a local doc build and view the draft release notes

Running ./build and viewing the local doc build is the best way to make sure that the changes you make build correctly. For more explanation of these steps, see the presto-docs README.

1. Change to the presto-docs directory of the clone of your fork of Presto in GitHub. Example:

   cd /Users/yourname/Documents/GitHub/presto/presto-docs

2. Pull the branch for the release notes PR. Example:

   gh pr checkout 25633

3. Generate a local docs build.

   ./build

4. In the local build, use a web browser to view the draft release notes page.

Section Headings

Section headings should be reviewed for Format and Order.

Format

1. Are the section headings (General Changes, Router Changes) in the correct format as shown in the Order of sections in the Release Notes Guidelines?

   For example, is there a section heading named “General Change Changes”, or other errors? Fix those.

2. Are the section headings for the Connector Changes correct? Are they in the following format “____ Connector Changes”?

3. Are MySQL, PostgreSQL, Oracle, MongoDB and other product names in the various Connector Changes headings correctly capitalized?

Order

1. Are the section headings (General Changes, Router Changes) in the correct order as shown in the Order of sections in the Release Notes Guidelines?

2. Are the connector section headings in the correct order? All of the Connector Changes headings should be grouped together, and be in alphabetical order.

Release Note Entries

Format

Each release note entry should:

• Be formatted as an unordered line item, like this line is.

• End with a PR # formatted as a link to the PR.

• Contain one or two sentences, ending with a period (.).

  Any release note entry longer than two sentences, consider revising it to be shorter and more concise.

An example of a correctly formatted release note entry:

• Add support for JSON type in MongoDB. #25089

Review process

For each release note entry:

1. Does each entry begin with a keyword from the Order of changes in the Release Notes Guidelines? If it does not, revise it so that it does.

2. Are all product names correctly spelled and capitalized?

3. Is each entry in the correct section? If not, move it to the correct section. For example, entries that should belong in Prestissimo, Router, or Connector-specific entries are often put into General Changes by the PR author.

   Note: If you move a release note entry to a section that's not currently in the release notes, add the section heading. See Order of sections in the Release Notes Guidelines for section headings.

4. Is the entry written in imperative present tense? For example, Add is correct but Added is not. For explanations and help, see Phrasing in the Release Notes Guidelines.

5. Is the entry written so that a non-developer can understand how this affects and improves the user experience for Presto? If not, revise the entry to make the value of the change in the PR understandable to a non-developer - so someone new to Presto can understand "this is why the code change in a PR matters".

   For each entry, ask yourself "would someone not an expert developer, and who is new to the Presto codebase, understand from these words in this release note entry what the code change in the linked PR fixed or improved?"

   For explanation and discussion, see Audience in the Release Notes Guidelines.

   Note: Reading the linked PR can be helpful to understand the change in the PR. The linked PR also shows the PR’s author to ask for additional information, or to revise the entry.

6. Would the reader be helped if you added a link in the entry to an appropriate page or heading in the Presto documentation? If yes, add it. For examples of link formatting, see Formatting in the Release Notes Guidelines.

7. If the entry does not describe a customer-facing change, consider revising it or deleting it.

8. Order the entries in each section so that they are in the correct order as shown in the Order of changes in the Release Notes Guidelines: all the Fix entries first, then all the Add entries, and so on.

Links

For each link in the body of the entry - to a different PR, or a documentation section, or a public Internet link - test and verify every link.

1. Some links will be broken because they are written in GitHub Markdown format – convert those links to .rst format. It is recommended to fix them locally, then run a new local doc build, then review the local build page, then test and verify the link is correct and working. For examples of link formatting, see Formatting in the Release Notes Guidelines.

2. Every entry must have at least one link to its PR that is automatically generated by the release process. In the local doc build, click the link and verify that it opens the correct PR.

3. Every entry should have only one link to a PR at the end. If there are two duplicate PR links at the end, delete the first one.

The Release Shepherd

Every release has a Release Shepherd who is a committer that volunteers to oversee the release. Their responsibilities for the release note PR are:

1. Review the PRs listed in the Missing Release Notes section of the release notes PR.

   a. Decide which (if any) of those PRs should have release notes added for this release.

   b. Write the needed entries and add them to the draft in the release notes PR. You can ask the author of the PR to write the draft entry and enter it as a comment in the release notes PR. If they don't reply in a timely manner, either draft a release note entry yourself, or decided to not include the PR in the release notes.

   c. Review and edit new entries following the guidelines in the Release Note Entries.

2. Select notable entries in the new release and copy those entries into the Highlights topic for the release notes.

   Note: Copy, not cut – do not delete the entry from its original section. All Highlights entries appear twice in the release notes: once in Highlights and a second time in General Changes, Router Changes, and so on.

3. Squash commits in the release notes PR.

4. When all comments and revisions are addressed and the release notes PR is reviewed and approved, merge it.