Solidity: Document or add Remix remappings when using upgradeable contracts

Background

When opening a Solidity contract in Remix, the Contracts library version is appended to the import paths to ensure Remix uses a specific pinned version of the library, for example:

import {GovernorUpgradeable} from "@openzeppelin/contracts-upgradeable@5.4.0/governance/GovernorUpgradeable.sol";

Problem

In some cases when the contract directly references a contract or interface, and if the same contract/interface is referenced transitively through a different import, the transitive version is using the original path which causes a conflict.

This particularly occurs between upgradeable and vanilla Contracts dependencies, because the upgradeable variants import vanilla contracts using full paths rather than relative paths. The actual conflict itself occurs in vanilla dependencies, and is due to the inclusion/exclusion of version in its path.

Example 1

For example, when using Governor with ERC20Votes and Upgradeability, the following are in the direct imports:

import {GovernorVotesUpgradeable} from "@openzeppelin/contracts-upgradeable@5.4.0/governance/extensions/GovernorVotesUpgradeable.sol";
import {IVotes} from "@openzeppelin/contracts@5.4.0/governance/utils/IVotes.sol";

but GovernorVotesUpgradeable.sol itself has (note this is without @5.4.0)

import {IVotes} from "@openzeppelin/contracts/governance/utils/IVotes.sol";

This causes a compile error:

TypeError: Invalid type for argument in function call. Invalid implicit conversion from contract IVotes to contract IVotes requested.
  --> contract-3b3900f8c2.sol:22:30:
   |
22 |         __GovernorVotes_init(_token);
   |                              ^^^^^^

Example 2

A similar issue occurs for Account with Modules and Upgradeability since https://github.com/OpenZeppelin/contracts-wizard/pull/609, with the following imports:

import {Account} from "@openzeppelin/contracts@5.4.0/account/Account.sol";
import {AccountERC7579Upgradeable} from "@openzeppelin/contracts-upgradeable@5.4.0/account/extensions/draft-AccountERC7579Upgradeable.sol";

where draft-AccountERC7579Upgradeable.sol has

import {Account} from "@openzeppelin/contracts/account/Account.sol";

This causes a compile error:

DeclarationError: Identifier already declared.
  --> @openzeppelin/contracts@5.4.0/account/Account.sol:30:5:
   |
30 |     error AccountUnauthorized(address sender);
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Note: The previous declaration is here:
  --> @openzeppelin/contracts/account/Account.sol:30:5:
   |
30 |     error AccountUnauthorized(address sender);
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Solution

Remappings should be defined to remap the unversioned library path @openzeppelin/contracts/ to the versioned one. This will ensure compilation of all imports uses the same specified version.

This can be done by adding remappings.txt with the content:

@openzeppelin/contracts/=@openzeppelin/contracts@5.4.0/

We should either document the above (somewhere in the Wizard UI before the users opens in Remix), or if possible automatically add this into the generated Remix project.

Start by locating the Wizard UI entry point for opening generated projects in Remix and the generated Remix project output. Compare the two import-conflict examples, then determine whether the completed behavior should add remappings.txt automatically or document the remapping before users open the project in Remix.