docs: clarify how to choose proxy type

[aspiers]

I think there is room for improvement in the documentation with regards to explaining how to choose between transparent and UUPS proxies. Let me give you my perspective as someone who is a newbie to upgradeable contracts, but otherwise an experienced developer.

Firstly I read https://docs.openzeppelin.com/contracts/4.x/api/proxy#transparent-vs-uups and several other good resources (including relevant EIPs), to learn the technical differences between transparent and UUPS proxies.

Next I read this overview:

• https://docs.openzeppelin.com/upgrades-plugins/1.x/

and then followed these instructions to make one of my OpenZeppelin ERC721 contracts upgradeable:

• https://docs.openzeppelin.com/upgrades-plugins/1.x/writing-upgradeable

and adjusted my Hardhat tests and deployment scripts according to:

• https://docs.openzeppelin.com/upgrades-plugins/1.x/hardhat-upgrades

I also consulted the contracts documentation which offered very similar info:

• https://docs.openzeppelin.com/contracts/4.x/upgradeable

and also this guide:

• https://docs.openzeppelin.com/learn/upgrading-smart-contracts

However none of these six resources mention that there is a way to choose between transparent and UUPS proxies! It was clear to me that there must be, because Transparent vs UUPS Proxies says:

The original proxies included in OpenZeppelin followed the Transparent Proxy Pattern. While this pattern is still provided, our recommendation is now shifting towards UUPS proxies, which are both lightweight and versatile.

So I kept hunting, with no luck.

Eventually I resorted to searching in the source, and found:

https://github.com/OpenZeppelin/openzeppelin-upgrades/blob/c73d34724238f04a91b248c3b345103a45945cda/packages/plugin-hardhat/src/deploy-proxy.ts#L61-L78

which led me to:

https://docs.openzeppelin.com/upgrades-plugins/1.x/api-hardhat-upgrades#common-options

where I finally realised that the trick is to pass { kind: 'uups' } to upgrades.deployProxy(). (I also see that the Truffle upgrades API offers the same thing.)

After more hunting, I eventually found UUPS Proxies: Tutorial (Solidity + JavaScript) - Smart Contracts / Guides and Tutorials - OpenZeppelin Community which is linked from https://docs.openzeppelin.com/openzeppelin/upgrades and is the clearest explanation. But ideally I would have found this information much more easily.

So I would suggest that at least some, if not all, of the first 6 links listed above should be modified to mention the mechanism for choosing the proxy type, and cross-link to the API docs and/or that tutorial.

Hope that feedback makes sense and is useful!

[robinxb]

Agreed, take me tons of time to figure out all these. Especially the { kind: 'uups' } and initializer args in upgrades.deployProxy()