Writing release notes

Pulsar release notes consist of the following parts:

• Core
• Java client
• WebSocket client
• C++ client
• Python client
• Go client
• Node.js client
• C# client

Prerequisite

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

brew install gh
gh auth login

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

# Replace 3.0.6 with the target version tag
VERSION_WITHOUT_RC=3.0.6
PREVIOUS_VERSION=3.0.5
# 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:

# 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)

PREVIOUS_VERSION=3.0.3
VERSION_WITHOUT_RC=3.0.4

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

Alternatively using "gh pr list"

gh pr list -L 1000 --search "is:pr is:merged label:release/2.10.6 label:cherry-picked/branch-2.10" --json title,number,url | jq -r '.[] | "- \(.title) ([#\(.number)](\(.url)))"' | sort | pbcopy

For feature releases, using the milestone:

gh pr list -L 1000 --search "is:pr is:merged milestone:4.0.0" --json title,number,url | jq -r '.[] | "- \(.title) ([#\(.number)](\(.url)))"' | sort | pbcopy

Update the release note page

The following steps are handled by the script ./scripts/generate_release_notes.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:

• Add the release note for C++ client 3.1.0
• Add the release note for Python client 3.0.0
• Add the release note for Pulsar 3.0.3

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