1# Making a new SDK release 2 3This guide shows how to make a new Perfetto SDK release. 4 5Before snapshotting a release, check that no [release-blockers](http://b/savedsearches/5776355) are 6open. 7 8Check out the code: 9 10```bash 11git clone https://android.googlesource.com/platform/external/perfetto 12cd perfetto 13``` 14 15Next, decide the version number for the new release (vX.Y). 16The major version number (X) is incremented on every release (monthly). 17The minor version number is incremented only for minor changes / fixes on top of the monthly 18release (cherry-picks on the releases/vN.x branch). 19 20Continue with the appropriate section below. 21 22## a) Creating a new major version 23 24Create a release branch for the new major version ("v16.x" here): 25 26```bash 27git fetch origin 28git push origin origin/master:refs/heads/releases/v16.x 29git fetch origin 30git checkout -b releases/v16.x -t origin/releases/v16.x 31``` 32 33Continue with [building the release](#building-and-tagging-the-release). 34 35## b) Bumping the minor version 36 37Check out the existing release branch ("5.x" here) and merge in the desired 38revision for the new release, resolving any conflicts you may encounter. 39 40```bash 41git checkout -b releases/v16.x -t origin/releases/v16.x 42``` 43 44If you only want to introduce one or two patches in the new release, consider 45cherry-picking them individually: 46 47```bash 48git cherry-pick <sha1> 49``` 50 51Otherwise, you can do a full merge: 52 53```bash 54git merge <sha1> 55``` 56 57Update the CHANGELOG with a dedicated entry for the new minor version. 58This is important because the 59[write_version_header.py](/tools/write_version_header.py) script, which is 60invoked by the build system, looks at the CHANGELOG to work out the latest 61v${maj}.${min} version. 62 63For an example see [r.android.com/1730332](https://r.android.com/1730332) 64 65```txt 66v16.1 - 2021-06-08: 67 Tracing service and probes: 68 * Cherry-pick of r.android.com/1716718 which missed the v16 branch ... . 69 70 71v16.0 - 2021-06-01: 72 ... 73``` 74 75## Building and tagging the release 76 771. Generate and commit the amalgamated source files. 78 79```bash 80tools/gen_amalgamated --output sdk/perfetto 81git add sdk/perfetto.{cc,h} 82git commit -m "Amalgamated source for vX.Y" 83``` 84 852. Check that the SDK example code works with the new release. 86 87```bash 88cd examples/sdk 89cmake -B build 90cmake --build build 91``` 92 933. Upload the new release for review. 94 95```bash 96git cl upload --no-squash 97``` 98 99If you get an error about a missing Change-Id field (`remote: ERROR: commit 100a7c7c4c: missing Change-Id in message footer`), install the commit-msg hook 101script and amend the change to make sure that field is present: 102 103```bash 104curl -Lo .git/hooks/commit-msg http://android-review.googlesource.com/tools/hooks/commit-msg 105chmod u+x .git/hooks/commit-msg 106git commit --amend 107``` 108 1094. Once the release has been reviewed and landed, create and push the tag for 110 it ("vX.Y" being the new version). 111 112```bash 113# This brings the branch up to date with the CL landed in the step above. 114git pull 115 116git status 117# Should print: Your branch is up to date with 'origin/releases/v16.x'. 118# Do NOT proceed if your branch has diverged from origin/releases/vX.X 119 120git tag -a -m "Perfetto vX.Y" vX.Y 121git push origin vX.Y 122``` 123 1245. Update the documentation to point to the latest release. 125 126 - [docs/instrumentation/tracing-sdk.md](/docs/instrumentation/tracing-sdk.md) 127 - [examples/sdk/README.md](/examples/sdk/README.md) 128 1296. Send an email with the CHANGELOG to perfetto-dev@ (internal) and to the 130 [public perfetto-dev](https://groups.google.com/forum/#!forum/perfetto-dev). 131 132## Creating a GitHub release with prebuilts 133 1347. Within few mins the LUCI scheduler will trigger builds of prebuilt binaries 135 on https://luci-scheduler.appspot.com/jobs/perfetto . Wait for all the bots 136 to have completed successfully and be back into the WAITING state. 137 1388. Run `tools/package-prebuilts-for-github-release vX.Y`. It will pull the 139 prebuilts under `/tmp/perfetto-prebuilts-vX.Y`. 140 - There must be 10 zips in total: linux-{arm,arm64,amd64}, 141 android-{arm,arm64,x86,x64}, mac-{amd64,arm64}, win-amd64. 142 - If one or more are missing it means that one of the LUCI bots failed, 143 check the logs (follow the "Task URL: " link) from the invocation log. 144 - If this happens you'll need to respin a vX.(Y+1) release with the fix 145 (look at the history v20.1, where a Windows failure required a respin). 146 1479. Open https://github.com/google/perfetto/releases/new and 148 - Select "Choose Tag" -> vX.Y 149 - "Release title" -> "Perfetto vX.Y" 150 - "Describe release" -> Copy the CHANGELOG, wrapping it in triple backticks. 151 - "Attach binaries" -> Attach the ten .zip files from the previous step. 152 15310. Run `tools/roll-prebuilts vX.Y`. It will update the SHA256 into the various 154 scripts under `tools/`. Upload a CL with the changes. 155 15611. Phew, you're done! 157