Introduce migration guide for breaking changes

The idea is that the document will contain one section for each breaking change with: - link to the PR introducing the change - brief description of the change - example of an error message - simple guide to fix existing scripts As an example, add entry for the recent change of the type of the `pid` and `tid` builtins.
bpftrace · Oct 8, 2024 · 07e8c21 · 07e8c21
1 parent 279301d
commit 07e8c21
Show file tree

Hide file tree

Showing 3 changed files with 33 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,7 @@ and this project adheres to
 #### Breaking Changes
 - Return `uint32` instead of `uint64` for `pid` and `tid` builtins
   - [#3441](https://github.com/bpftrace/bpftrace/pull/3441)
+  - [Migration guide](docs/migration_guide.md#pid-and-tid-builtins-return-uint32)
 #### Added
 - Add `--dry-run` CLI option
   - [#3203](https://github.com/bpftrace/bpftrace/pull/3203)

diff --git a/README.md b/README.md
@@ -15,6 +15,7 @@ bpftrace is a high-level tracing language for Linux. bpftrace uses LLVM as a bac
 - [Contribute](#contribute)
 - [Development](#development)
 - [Support](#support)
+- [Migration guide](docs/migration_guide.md)
 - [Probe types](#probe-types)
 - [Plugins](#plugins)
 - [License](#license)

diff --git a/docs/migration_guide.md b/docs/migration_guide.md
@@ -0,0 +1,31 @@
+# Breaking changes (migration guide)
+
+This document lists changes introduced in bpftrace which break backwards
+compatibility in some way. Each entry should contain:
+- a link to the PR introducing the change
+- a brief description of the change
+- an example of an error message
+- a simple guide to fix existing scripts
+
+## Versions 0.21.x (or earlier) to 0.22.x (or later)
+
+### `pid` and `tid` builtins return `uint32`
+
+https://github.com/bpftrace/bpftrace/pull/3441
+
+Previously, `pid` and `tid` builtins returned `uint64` so it is now possible to
+get an error when storing the builtin in a variable and overriding it with
+`uint64` later:
+```
+# bpftrace -e 'BEGIN { $x = pid; $x = cgroup; }'   # cgroup is uint64
+stdin:1:19-30: ERROR: Integer size mismatch. Assignment type 'uint64' is larger than the variable type 'uint32'.
+BEGIN { $x = pid; $x = cgroup; }
+                  ~~~~~~~~~~~
+```
+
+To mitigate such an error, just typecast `pid` or `tid` to `uint64`:
+```
+# bpftrace -e 'BEGIN { $x = (uint64)pid; $x = cgroup; }'
+Attaching 1 probe...
+```
+