Add Hardhat Upgrades docs for Hardhat 3

[ericglau]

Summary

Adds Hardhat 3 documentation for the Hardhat Upgrades plugin (@openzeppelin/hardhat-upgrades 4.0.0, to be released). The existing Hardhat 2 docs are preserved as legacy under /upgrades-plugins/hardhat-2/* with an "Outdated Version" banner. Pre-existing URLs (/upgrades-plugins/hardhat-upgrades, /upgrades-plugins/api-hardhat-upgrades) remain live and now describe Hardhat 3 — no redirects. Also adds a migration guide to /upgrades-plugins/migrate-from-hardhat-2 and adds nav entries.

Type of Change

• New documentation
• Documentation update/revision
• Restructure/reorganize content
• Update API documentation

Related Issues

OpenZeppelin/openzeppelin-upgrades#1191
OpenZeppelin/openzeppelin-upgrades#1241
OpenZeppelin/openzeppelin-foundry-upgrades#121

Checklist

• Build succeeds locally with pnpm run build
• Lint is successful when running pnpm run check
• Docs follow OpenZeppelin Documentation Standards

Additional Notes

• Only the Hardhat-specific pages are versioned to support both Hardhat 3 and 2. Other pages in the Upgrades section (e.g. Foundry and core) remain unversioned since the latest versions of those are intended to remain backwards compatible.

[ericglau]

Doc previews of Hardhat 3 related content:

• https://deploy-preview-147--openzeppelin-docs-v2.netlify.app/upgrades-plugins/hardhat-upgrades
• https://deploy-preview-147--openzeppelin-docs-v2.netlify.app/upgrades-plugins/migrate-from-hardhat-2
• https://deploy-preview-147--openzeppelin-docs-v2.netlify.app/upgrades-plugins/api-hardhat-upgrades

Hardhat 2 content are moved to "Previous Versions" under here:

• https://deploy-preview-147--openzeppelin-docs-v2.netlify.app/upgrades-plugins/hardhat-2/hardhat-upgrades
• https://deploy-preview-147--openzeppelin-docs-v2.netlify.app/upgrades-plugins/hardhat-2/api-hardhat-upgrades

[ericglau]

Hardhat 3 documentation structure and coverage

This PR updates the Upgrades Plugins docs for the Hardhat 3 release.

The documentation is organized around three user paths:

1. New Hardhat 3 users land on the current Hardhat Upgrades pages:

   • Using with Hardhat
   • OpenZeppelin Hardhat Upgrades API

2. Existing Hardhat 2 users get a dedicated migration path:

   • Migrating from Hardhat 2
   • the previous release's Hardhat 2 usage/API pages under hardhat-2/

3. Users writing Solidity tests in Hardhat 3 get a section explaining the @openzeppelin/foundry-upgrades integration, including the required FOUNDRY_OUT, npmFilesToBuild, FFI, and filesystem-permission setup.

Coverage goals

The main goal is to make the Hardhat 3 path feel like the default path for new users, while keeping the Hardhat 2 path easy to find for existing projects. The current pages explain the new Hardhat 3 setup model: explicit plugin registration, creating an upgradesApi or defenderApi object to access the Upgrades API functions, and sharing a Hardhat network connection across related operations.

The migration guide is meant to be practical rather than exhaustive: it highlights the user-visible breaking changes and gives before/after examples for config, imports, scripts, tasks, tests, and source code verification. The Solidity-test section is included as an optional path for users who want to use Hardhat 3 Solidity tests with @openzeppelin/foundry-upgrades, without making it look required for normal Hardhat Upgrades usage.

Defender documentation remains in place, with Hardhat 3 users directed back to the new factory/connection pattern where needed.

Assumptions to sanity-check

1. The split between current Hardhat 3 pages, archived Hardhat 2 pages, and a dedicated migration guide is the right layout.
2. The migration guide covers the main user-visible breaking changes: ESM/config plugin registration, explicit factory imports, async API creation, shared network connections, and peer dependency changes.
3. The Solidity-test section includes the right amount of setup detail without making Solidity tests look required for normal Hardhat Upgrades usage.
4. The docs make it clear enough that Hardhat 2 users should stay on the previous release's Hardhat 2 docs, while new Hardhat 3 users should follow the current pages.
5. There are no missing user-facing concepts that should block the Hardhat 3 full release.

Relevant files:

• content/upgrades-plugins/hardhat-upgrades.mdx
• content/upgrades-plugins/api-hardhat-upgrades.mdx
• content/upgrades-plugins/migrate-from-hardhat-2.mdx
• content/upgrades-plugins/hardhat-2/hardhat-upgrades.mdx
• content/upgrades-plugins/hardhat-2/api-hardhat-upgrades.mdx
• content/upgrades-plugins/defender-deploy.mdx
• src/navigation/ethereum-evm.json

[netlify]

✅ Deploy Preview for openzeppelin-docs-v2 ready!

Name	Link
🔨 Latest commit	13eb8f7
🔍 Latest deploy log	https://app.netlify.com/projects/openzeppelin-docs-v2/deploys/6a1838bd51f09a0008ce1f0a
😎 Deploy Preview	https://deploy-preview-147--openzeppelin-docs-v2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[stevep0z]

LGTM! Nice work on all of this @ericglau and team.