Skip to main content

Writing release notes

Pulsar release notes consist of the following parts:

Prerequisite​

To generate release notes, you are suggested to install the GitHub CLI and authenticate first:

brew install gh
gh auth login

Set these variables in the shell

VERSION_WITHOUT_RC=4.0.14
PREVIOUS_VERSION=4.0.13

Go to the directory where you have apache/pulsar-site checked out:

PULSAR_SITE_PATH=$(pwd)

Pre-set the destination for release notes

RELEASE_NOTES_PATH="${PULSAR_SITE_PATH}/release-notes/versioned/pulsar-${VERSION_WITHOUT_RC}.md"

Register the new released version to releases.json, data/release-pulsar.js and data/release-java.js files​

cd $PULSAR_SITE_PATH
# Replace apache/pulsar with the component repo
./scripts/register_new_version.py $VERSION_WITHOUT_RC $PREVIOUS_VERSION $(gh release view "v$VERSION_WITHOUT_RC" -R apache/pulsar --json author,publishedAt | jq -r '[.author.login, .publishedAt] | join(" ")')

Alternatively, for a tag instead of a release:

cd $PULSAR_SITE_PATH
# For a tag instead of a release
./scripts/register_new_version.py $VERSION_WITHOUT_RC $PREVIOUS_VERSION $(cd $PULSAR_PATH && git show -s --format="%ae %aI" "v$VERSION_RC" | tail -n 1 | sed 's/@.* / /')

Generate release notes​

There isn't a definite way yet. You will need to categorize the PRs into different sections manually and edit the release note file. These commands are used to generate the release note entries.

Here are 2 approaches:

Using "git log" (copies output to clipboard using pbcopy)

cd $PULSAR_PATH
git log --reverse --oneline v$PREVIOUS_VERSION..v$VERSION_WITHOUT_RC | colrm 1 12 | sed 's/\] \[/][/' | sed 's/^[[:space:]]*//' | awk -F ']' '{
    if ($1 ~ /^\[/) {
        print $1 "]" $2 " | " $0
    } else {
        print "[zzz] | " $0
    }
}' | sort | sed 's/^[^|]* | //' | sed 's/\(#\([0-9]\+\)\)/[#\2](https:\/\/github.com\/apache\/pulsar\/pull\/\2)/g' | sed 's/^/- /' | sed 's/</\&lt;/g' | sed 's/>/\&gt;/g' \
>> $RELEASE_NOTES_PATH

Alternatively using "gh pr list"

cd $PULSAR_PATH
gh pr list -L 1000 --search "is:pr is:merged label:release/$VERSION_WITHOUT_RC label:cherry-picked/$VERSION_BRANCH" --json title,number,url | jq -r '.[] | "- \(.title) ([#\(.number)](\(.url)))"' | sort >> $RELEASE_NOTES_PATH

For feature releases, using the milestone:

cd $PULSAR_PATH
gh pr list -L 1000 --search "is:pr is:merged milestone:$VERSION_WITHOUT_RC" --json title,number,url | jq -r '.[] | "- \(.title) ([#\(.number)](\(.url)))"' | sort >> $RELEASE_NOTES_PATH

Categorizing the release note entries​

There is a separate script that can automatically categorize the release note items.

cd $PULSAR_SITE_PATH
./scripts/release_notes_reorder_script.py $RELEASE_NOTES_PATH

You need to check the results and sometimes manually reorder the entries.

If you are releasing multiple maintenance versions at once, you can use another release as the reference for ordering, so you do not have to repeat the same manual reordering.

cd $PULSAR_SITE_PATH
./scripts/release_notes_reorder_script.py release-notes/versioned/pulsar-X.Y.Z.md $RELEASE_NOTES_PATH

Creating Java client release notes​

Copy the "Client" and applicable entries from "Library updates" into the client-java release notes.

Update release notes in GitHub releases​

Copy the file content to clipboard and paste to correct location by editing the release notes at https://github.com/apache/pulsar/releases

cat $RELEASE_NOTES_PATH | pbcopy

Update the release note page​

The following steps were handled by the script ./scripts/register_new_version.py.

  1. Copy the related release notes entries and add a versioned release note file.
  2. Update the version metadata files (release-*.js). For apache/pulsar releases, this means updating release-java.js (Java client) and release-pulsar.js (Pulsar).
  3. For every apache/pulsar release, you should add a <release-version> entry to the corresponding place in the releases.json file.

Update swagger files. ref: swagger files

To preview the result, follow the instructions for previewing content.

Submit the release note​

Submit a PR against the site repo with the added version release note file and updated version metadata files.

Here are some examples:

Check whether the release information is shown on the Pulsar Release Note page after the website is updated and built successfully.

Was this helpful?
💡 Suggest changes🛟 Get support