Writing release notes for Drupal core releases

Background information

Release note snippets for each issue are best written by someone working on the issue. (How to write a release note snippet for an issue.)

Issue contributors should write a release note snippet for any potentially significant change, because the snippet itself will help reviewers and committers understand the impact of the issue. Release note snippets can be used for both the release notes (which summarize the potentially disruptive changes in a release) and the release highlights (valuable improvements in a release, whether user- or developer-facing). Always explain what changed, who is affected, and what (if anything) the affected users need to do as a result.

Core release managers are ultimately responsible for all release notes, but the release notes for minor and major releases are edited in collaboration with the core committer team facilitators as well as other committers and volunteer core contributors. (For security releases, the release managers work together with the Drupal Security Team to draft and edit the release notes.)

General requirements for a core release's notes

The goal is to give a brief explanation of disruptive changes since the last release.

The content of release notes is written for sites owners and developers. However, the target audience is different for alpha and beta releases. For alpha and beta releases the notes are written primarily for early testers.  Specifically, for a major alpha release the intended audience is mostly core developers and bleeding-edge contrib. And for a minor alpha the intended audience is  "early adopter" site owners and all contrib developers. This means that the release notes for alphas and betas include details that might not be present in the final RC, minor or major release notes.

Once an issue has a valid release note snippet it can be added to the draft release notes. The text and style of the snippet may need to change.

Create the working document

Release notes are drafted in Google Docs in the core committer team folder prior to the release.

For minor and major releases create the release note in the sub folder of  the"Minor and major release preparation" folder. For a patch release use the folder 'Patch release notes drafts'.

Change the document permissions to allow commenting permission to "anyone with the link", so that the wider core community can help with the revision process.

Create the initial outline by referring to the most recent release of the same type. For example:

• The 9.3.11 bugfix release notes iterate on the notes for the previous bugfix release in 9.3.10.
• The 9.3.12 security release notes iterate on the previous security release's notes in 9.3.9.
• The 9.4.0-beta1 release notes iterate on the outline for the 9.3.0-beta1 release notes.

Reviewing release notes

• Read all the text for clarity and readability.
• Fix typos or markup errors.
• Suggest improvements and simplifications where relevant using the "suggest" feature.
• If a given note doesn't seem like it belongs in the release notes, leave a comment on the draft document to discuss it with committers.

For minor releases:

• Read the whole release notes draft.
• If there are more than 3-4 new release notes since alpha1, group them into logical sections. See past release notes for examples of the headers used.

Formatting

1. Each release note should be in bulleted lists, with newlines between the paragraph and the <li> tags so that Drupal.org's release node HTML filter renders them cleanly. For example:
   

   <li>
    
   [Single release note]
    
   </li>
   

2. Consolidate notes that are about the same thing (e.g., multiple updates for a given dependency, or two disruptive changes to the same API).
3. Individual notes should link a change record (except for dependency updates).
4. Links to core issue nodes should be avoided and a change record used instead. If an issue node must be included use, use the [#1234567] issue link syntax.
5. All link texts should be meaningful and unique out of context for accessibility:
   • ❌ Don't use "click here".
   • ❌ Don't use See https://drupal.org/node/nid.
   • ❌ Don't use Read the <a href="https://drupal.org/node/nid">change record</a> for more information..