base / base/contracts

docs: `foundryup` recommendation can install a version different from the repository-pinned Foundry toolchain

Open
#403 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Solidity
Stars
325
Forks
245
Avg merge
13h 48m
Merged PRs (30d)
18

Description

## Summary

The repository pins Foundry to a specific version in `.mise.toml` for deterministic builds, ABI/storage snapshots, and `semver-lock` hashes.

However, the README currently recommends running:

```bash
foundryup
````

when `semver-lock` fails because of a Foundry version mismatch.

`foundryup` normally updates Foundry independently of the repository's `.mise.toml` pin. This can leave contributors on a different Foundry version from the one explicitly required by the repository and CI.

The recovery instruction can therefore make the original version-mismatch problem worse rather than resolving it.

## Affected Files

* `README.md`
* `.mise.toml`

## Current Behavior

`.mise.toml` explicitly states that the repository pins tooling so contributors and CI execute builds, tests, snapshots, and semver-lock generation with byte-identical tooling.

The current pin is:

```toml
[tools]
foundry = "1.5.1"
```

The README, however, says that if `semver-lock` still fails because of a Foundry version mismatch, contributors should run:

```bash
foundryup
just semver-lock
```

This does not guarantee installation of Foundry `1.5.1`.

## Why This Is a Problem

A contributor can follow the README exactly and still end up using a toolchain different from CI.

Example flow:

1. Contributor clones the repository.
2. Contributor has an older or newer Foundry version.
3. `just semver-lock` fails.
4. Contributor follows the documented recovery instructions.
5. `foundryup` installs the current Foundry release.
6. The installed version is not necessarily the repository-pinned `1.5.1`.
7. Generated semver-lock hashes or snapshots can still differ from CI.

This contradicts the reproducibility requirement documented in `.mise.toml`.

## Expected Behavior

The README should direct contributors to install the exact repository-pinned toolchain.

For example:

```bash
mise install
mise exec -- just semver-lock
```

or otherwise explicitly install the same Foundry version used by CI.

## Suggested Fix

Replace:

````markdown
If CI still rejects it (Foundry version mismatch), update your local Foundry first:

```bash
foundryup
just semver-lock
````

````

with something similar to:

```markdown
If CI still rejects it because of a Foundry version mismatch, install the repository-pinned toolchain:

```bash
mise install
mise exec -- just semver-lock
````

The Foundry version is pinned in `.mise.toml` and should match CI.

````

## Additional Improvement

The setup section currently also says:

```bash
just install-foundry
````

Consider making `mise install` the canonical setup path if `.mise.toml` is intended to be the authoritative source of tool versions.

Alternatively, `just install-foundry` could explicitly install the version defined by `.mise.toml`.

## Impact

This is primarily a developer-experience and build-reproducibility issue.

It can cause:

* unnecessary CI failures;
* semver-lock hash mismatches;
* snapshot differences;
* contributors regenerating artifacts with unsupported tooling;
* confusion when following the documented remediation steps.

## Environment

Repository:

`base/contracts`

Branch:

`main`

Affected documentation:

`README.md`

Toolchain definition:

`.mise.toml`

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.