Making a new SDK release

This guide shows how to make a new Perfetto SDK release.

Before snapshotting a release, check that no release-blockers are open.

Check out the code:

git clone cd perfetto

Next, decide the version number for the new release (vX.Y). The major version number (X) is incremented on every release (monthly). The minor version number is incremented only for minor changes / fixes on top of the monthly release (cherry-picks on the releases/vN.x branch).

Continue with the appropriate section below.

a) Creating a new major version

Create a release branch for the new major version ("v16.x" here):

git fetch origin git push origin origin/master:refs/heads/releases/v16.x git fetch origin git checkout -b releases/v16.x -t origin/releases/v16.x

Continue with building the release.

b) Bumping the minor version

Check out the existing release branch ("5.x" here) and merge in the desired revision for the new release, resolving any conflicts you may encounter.

git checkout -b releases/v16.x -t origin/releases/v16.x

If you only want to introduce one or two patches in the new release, consider cherry-picking them individually:

git cherry-pick <sha1>

Otherwise, you can do a full merge:

git merge <sha1>

Update the CHANGELOG with a dedicated entry for the new minor version. This is important because the script, which is invoked by the build system, looks at the CHANGELOG to work out the latest v${maj}.${min} version.

For an example see

v16.1 - 2021-06-08: Tracing service and probes: * Cherry-pick of which missed the v16 branch ... . v16.0 - 2021-06-01: ...

Building and tagging the release

  1. Generate and commit the amalgamated source files.
tools/gen_amalgamated --output sdk/perfetto git add sdk/perfetto.{cc,h} git commit -m "Amalgamated source for vX.Y"
  1. Check that the SDK example code works with the new release.
cd examples/sdk cmake -B build cmake --build build
  1. Upload the new release for review.
git cl upload --no-squash

If you get an error about a missing Change-Id field (remote: ERROR: commit a7c7c4c: missing Change-Id in message footer), install the commit-msg hook script and amend the change to make sure that field is present:

curl -Lo .git/hooks/commit-msg chmod u+x .git/hooks/commit-msg git commit --amend
  1. Once the release has been reviewed and landed, create and push the tag for it ("vX.Y" being the new version).
# This brings the branch up to date with the CL landed in the step above. git pull git status # Should print: Your branch is up to date with 'origin/releases/v16.x'. # Do NOT proceed if your branch has diverged from origin/releases/vX.X git tag -a -m "Perfetto vX.Y" vX.Y git push origin vX.Y
  1. Update the documentation to point to the latest release.

  2. Send an email with the CHANGELOG to perfetto-dev@ (internal) and to the public perfetto-dev.

Creating a GitHub release with prebuilts

  1. Within few mins the LUCI scheduler will trigger builds of prebuilt binaries on . Wait for all the bots to have completed succesfully and be back into the WAITING state.

  2. Run tools/package-prebuilts-for-github-release vX.Y. It will pull the prebuilts under /tmp/perfetto-prebuilts-vX.Y.

    • There must be 9 zips in total: linux-{arm,arm64,amd64}, android-{arm,arm64,x86,x64}, mac-amd64, win-amd64.
    • If one or more are missing it means that one of the LUCI bots failed, check the logs (follow the "Task URL: " link) from the invocation log.
    • If this happens you'll need to respin a vX.(Y+1) release with the fix (look at the history v20.1, where a Windows failure required a respin).
  3. Open and

    • Select "Choose Tag" -> vX.Y
    • "Release title" -> "Perfetto vX.Y"
    • "Describe release" -> Copy the CHANGELOG, wrapping it in triple backticks.
    • "Attach binaries" -> Attache the nine .zip files from the previous step.
  4. Run tools/roll-prebuilts vX.Y. It will update the SHA256 into the various scripts under tools/. Upload a CL with the changes.

  5. Phew, you're done!