Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 22 additions & 9 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,23 +51,36 @@ These constants are used by the runner to download and install the correct versi

### Pinned binary hashes

Every binary the runner downloads at install time (the patched valgrind `.deb`, the memtrack installer, the exec-harness installer, the mongo-tracer installer) is SHA-256-pinned. Each artifact keeps its version, URL template, and hash together in `src/binary_pins.rs`.
Every binary the runner downloads at install time is SHA-256-pinned. The pins live in two places:

When you bump a pinned version, regenerate the hash for each affected URL and update the matching pin record:
- **`src/binary_pins.rs`** — the patched valgrind `.deb`, the memtrack installer, the exec-harness installer, and the mongo-tracer installer. Each artifact keeps its version, URL template, and hash together in a pin record.
- **`src/executor/helpers/introspected_golang/go.sh`** — the go-runner installer published by [CodSpeedHQ/codspeed-go](https://github.com/CodSpeedHQ/codspeed-go), one `<version> <sha256>` row per release in the `GO_RUNNER_INSTALLER_SHA256S` table. `DEFAULT_GO_RUNNER_VERSION` (just below the table) selects the row used by default.

```bash
curl -sL '<url>' | sha256sum
```
When you bump a pinned version (or add a new go-runner row), update the matching pin record / table row with the new version and its SHA-256.

For valgrind, that is one hash per supported `(distro_version, arch)` combination. `src/binary_pins.rs` also holds `VALGRIND_CODSPEED_VERSION` (the upstream semver, used to detect an already-installed copy) and `VALGRIND_DEB_REV` (the `.deb` revision suffix); the `.deb` package version is `{VALGRIND_CODSPEED_VERSION}-{VALGRIND_DEB_REV}`. Bump `VALGRIND_CODSPEED_VERSION` for a new upstream release, and `VALGRIND_DEB_REV` when the same upstream is repackaged.
#### Getting the hash from the verification test

The fastest way to get the right hash is to let the verification test tell you, instead of computing it by hand:

1. Add the new version with a **placeholder** hash — any 64 hex chars work (e.g. copy an existing row's hash).
2. Run the network-bound verification tests, which download every pinned URL and assert the bytes match the declared hash:

After updating, run the network-bound verification test that downloads every pinned URL and checks the bytes against the declared hash:
```bash
GITHUB_ACTIONS=true cargo test all_pinned
```

The `all_pinned` filter matches **both** tests at once — `all_pinned_binaries_match_their_declared_sha256` (the `src/binary_pins.rs` pins) and `all_pinned_go_runner_installers_match_their_declared_sha256` (the go-runner table). They are skipped unless `GITHUB_ACTIONS` is set.
3. The test fails with `expected <placeholder>, got <actual>`. Paste the `<actual>` value into the table row / pin record and re-run — it should now pass.

You can also compute a hash directly if you prefer:

```bash
GITHUB_ACTIONS=true cargo test --lib binary_pins::tests::all_pinned_binaries_match_their_declared_sha256
curl -sL '<url>' | sha256sum
```

This is also run in CI, but running it locally before opening the PR avoids a release-time round trip if a hash is wrong.
For valgrind, that is one hash per supported `(distro_version, arch)` combination. `src/binary_pins.rs` also holds `VALGRIND_CODSPEED_VERSION` (the upstream semver, used to detect an already-installed copy) and `VALGRIND_DEB_REV` (the `.deb` revision suffix); the `.deb` package version is `{VALGRIND_CODSPEED_VERSION}-{VALGRIND_DEB_REV}`. Bump `VALGRIND_CODSPEED_VERSION` for a new upstream release, and `VALGRIND_DEB_REV` when the same upstream is repackaged.

These tests also run in CI, but running them locally before opening the PR avoids a release-time round trip if a hash is wrong.

### Releasing the Main Runner

Expand Down
3 changes: 2 additions & 1 deletion src/executor/helpers/introspected_golang/go.sh
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,10 @@ GO_RUNNER_INSTALLER_SHA256S="
1.0.2 4e4ecfb1888ced253f0acbbc132db0b1d7e99351d40f3eff789a518a6130ee35
1.1.0 d16e0e14bdfaea61a6da1d46d7b3b36f940b64335c8affbdc85b802d6e949a97
1.2.0 072876ccd43b8c73c123df206eda4b1f82f9ff03b1330efe35e5eaa5c1b6cefe
1.2.1 5c90675148a23fd550681033b5589b39b8e66a8ea372d27befd580be0cc535f4
"

DEFAULT_GO_RUNNER_VERSION="1.2.0"
DEFAULT_GO_RUNNER_VERSION="1.2.1"

get_go_runner_installer_sha256() {
if ! awk -v v="$1" '$1==v{print $2; f=1} END{exit !f}' <<<"$GO_RUNNER_INSTALLER_SHA256S"; then
Expand Down
Loading