docs: `foundryup` recommendation can install a version different from the repository-pinned Foundry toolchain
- 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.