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

Fetch the release metadata

# Replace 3.0.6 with the target version tag
VERSION_WITHOUT_RC=3.0.6
# Replace apache/pulsar with the component repo
gh release view "v$VERSION_WITHOUT_RC" -R apache/pulsar --json author,tagName,publishedAt

Fetch the release note

# Replace 3.0.6 with the target version tag
VERSION_WITHOUT_RC=3.0.6
# Replace apache/pulsar with the component repo
gh release view "v$VERSION_WITHOUT_RC" -R apache/pulsar --json body --jq .body

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
# Replace apache/pulsar with the component repo
./scripts/register_new_version.py $VERSION_WITHOUT_RC $(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 $(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.

Here are 2 approaches:

Using "git log"

PREVIOUS_VERSION=3.0.3
VERSION_WITHOUT_RC=3.0.4
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/^/- /'

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

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.
4. 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.