Update deprecation docs, minor fixup (MetaMask#206)

* Update chain change page reload docs

* Add comment about eth_requestAccounts

* Add comment about legacy-web3

Co-authored-by: Austin Akers <[email protected]>

docs/guide/create-dapp.md

@@ -239,7 +239,8 @@ Under your `onClickInstall` function write/insert this code.
 ```javascript
 const onClickConnect = async () => {
   try {
-    //Will Start the MetaMask Extension
+    // Will open the MetaMask UI
+    // You should disable this button while the request is pending!
     await ethereum.request({ method: 'eth_requestAccounts' });
   } catch (error) {
     console.error(error);

docs/guide/ethereum-provider.md

@@ -45,7 +45,7 @@ if (provider) {
 We are in the process of shipping changes that will break certain Ethereum web applications.
 All future major versions of MetaMask on all platforms will be affected.
 To ensure that your site won't break, you need to handle these changes today.
-We will make an announcement on  [this GitHub issue](https://github.com/MetaMask/metamask-extension/issues/8077) when the changes ship.
+We will make an announcement on [this GitHub issue](https://github.com/MetaMask/metamask-extension/issues/8077) when the changes ship.
 
 All consumers of MetaMask's provider may be affected by the `eth_chainId` bug (see [next subsection](#window-ethereum-api-changes)).
 Other than that, if you are new to using the provider, you do not have to worry about these changes, and can skip ahead [to the next section](#api).
@@ -65,6 +65,8 @@ We will:
 - Remove the `ethereum.publicConfigStore` object
   - This object was, despite its name, never intended for public consumption.
     Its removal _may_ affect those who do not use it directly, e.g. if another library you use relies on the object.
+- Remove the [`ethereum.autoRefreshOnNetworkChange`](#ethereum-autorefreshonnetworkchange-to-be-removed) property
+  - Consumers will still be able to set this property on the provider, it just won't do anything.
 
 These changes _may_ break your website.
 Please read our [Migration Guide](./provider-migration.html) for more details.
@@ -143,11 +145,11 @@ The value of this property can change at any time, and should not be exclusively
 
 A hexadecimal string representing the current chain ID.
 
-### ethereum.autoRefreshOnNetworkChange
+### ethereum.autoRefreshOnNetworkChange (TO BE REMOVED)
 
-::: warning
+::: danger DANGER
 The value of this property will only affect MetaMask's behavior if `window.web3` is accessed during the page lifecycle.
-When `window.web3` [is removed](#window-web3-removal), either the effects of this property will change, or it will be removed.
+When `window.web3` [is removed](#window-web3-removal), this property will be removed as well.
 
 As the consumer of this API, it is your responsbility to handle chain changes using the [`chainChanged` event](#chainChanged).
 We recommend reloading the page on `chainChange` unless you have good reason not to.
@@ -253,7 +255,7 @@ ethereum.on('accountsChanged', (accounts) => {
 ethereum.on('chainChanged', (chainId) => {
   // Handle the new chain.
   // Correctly handling chain changes can be complicated.
-  // We recommend reloading the page unless you have a very good reason not to.
+  // We recommend reloading the page unless you have good reason not to.
   window.location.reload();
 });
 ```
@@ -315,7 +317,7 @@ The MetaMask provider emits this event when the currently connected chain change
 All RPC requests are submitted to the currently connected chain.
 Therefore, it's critical to keep track of the current chain ID by listening for this event.
 
-We _strongly_ recommend reloading the page on chain changes, unless absolutely necessary not to.
+We _strongly_ recommend reloading the page on chain changes, unless you have good reason not to.
 
 ```javascript
 ethereum.on('chainChanged', (_chainId) => window.location.reload());

docs/guide/getting-started.md

@@ -60,6 +60,7 @@ You can listen for changes using events too, see ([the API reference](./ethereum
 "Connecting" or "logging in" to MetaMask effectively means "to access the user's Ethereum account(s)".
 
 You should **only** initiate a connection request in response to direct user action, such as clicking a button.
+You should **always** disable the "connect" button while the connection request is pending.
 You should **never** initiate a connection request on page load.
 
 We recommend that you provide a button to allow the user to connect MetaMask to your dapp.

docs/guide/provider-migration.md

@@ -5,7 +5,7 @@ This documentation is for Ethereum application developers.
 As a MetaMask user, you don't need to do anything!
 :::
 
-::: danger Deadline Imminent
+::: danger Breaking Changes Imminent
 We are in the process of shipping all of these changes.
 These changes may ship at any time, and all future major versions of MetaMask on all platforms will be affected.
 
@@ -25,14 +25,20 @@ You can follow [this GitHub issue](https://github.com/MetaMask/metamask-extensio
 
 ## Replacing `window.web3`
 
+::: warning Pages Will No Longer Reload on Chain Changes
+With the removal of `window.web3`, MetaMask will no longer automatically reload the page on chain/network changes.
+
+Please see [Handling the Removal of `ethereum.autoRefreshOnNetworkChange`](#handling-the-removal-of-ethereum-autorefreshonnetworkchange) for details.
+:::
+
 For historical reasons, MetaMask has injected [`[email protected]`](https://github.com/ethereum/web3.js/tree/0.20.7) into all web pages.
 This version of `web3` is deprecated, [has known security issues](https://github.com/ethereum/web3.js/issues/3065), and is no longer maintained by the [web3.js](https://github.com/ethereum/web3.js/) team, so the only way we can continue providing a secure experience to our developers is by removing this library.
 
 If your website relies on our `window.web3` object, your Ethereum-related functionality will break when we stop injecting `window.web3`.
 Continue reading to learn more about the migration options. Some are as simple as a one-line change.
 
 ::: tip Tip
-Regardless of how you choose to migrate, you will probably want to read the `[email protected]` documentation, which you can find [here](https://github.com/ethereum/web3.js/blob/0.20.7/DOCUMENTATION.md).
+Regardless of how you choose to migrate, you may want to read the `[email protected]` documentation, which you can find [here](https://github.com/ethereum/web3.js/blob/0.20.7/DOCUMENTATION.md).
 :::
 
 ### Using `window.ethereum` Directly
@@ -46,12 +52,7 @@ For example, here are a couple of actions performed using first `window.web3`, a
 ### Using an Updated Convenience library
 
 If you decide that you need a convenience library, you will have to convert your usage of `window.web3` to an updated convenience library.
-We recommend one of the following options.
-
-- [`ethers`](https://npmjs.com/package/ethers)
-  - [Documentation](https://docs.ethers.io/)
-- [`web3`](https://npmjs.com/package/web3)
-  - [Documentation](https://web3js.readthedocs.io)
+We recommend [`ethers`](https://npmjs.com/package/ethers) ([documentation](https://docs.ethers.io/)).
 
 ### Using `@metamask/legacy-web3`
 
@@ -63,7 +64,7 @@ It is not future-proof, and it is not guaranteed to work.
 Finally, if you just want your web3 site to continue to work, we created [`@metamask/legacy-web3`](https://npmjs.com/package/@metamask/legacy-web3).
 This package is a drop-in replacement for our `window.web3` that you can add to your web3 site even before MetaMask stops injecting `window.web3`.
 
-`@metamask/legacy-web3` should work exactly like our injected `window.web3`, but _we cannot guarantee that it works perfectly_.
+`@metamask/legacy-web3` should work exactly like our injected `window.web3`, including by refreshing the page on chain/network changes, but _we cannot guarantee that it works perfectly_.
 We will not fix any future incompatibilities between `[email protected]` and MetaMask itself, nor will we fix any bugs in `[email protected]` itself.
 
 For installation and usage instructions, please see [npm](https://npmjs.com/package/@metamask/legacy-web3).
@@ -128,4 +129,13 @@ Although it is possible that your dependencies use the `publicConfigStore`, we h
 - `ethers`
 - `web3` (web3.js)
 
+### Handling the Removal of `ethereum.autoRefreshOnNetworkChange`
+
+The `ethereum.autoRefreshOnNetworkChange` is a mutable boolean property used to control whether MetaMask reloaded the page on chain/network changes.
+However, it only causes the page to be reloaded if the a script access a property on `window.web3`.
+Therefore, this property will be removed along with `window.web3`.
 
+Despite this, we still recommend reloading the page on chain changes.
+Some convenience libraries, such as [ethers](https://www.npmjs.com/package/ethers), will continue to reload the page by default.
+If you don't use such a convenience library, you'll have to reload the page manually.
+Please see the [`chainChanged` event](./ethereum-provider.html#chainchanged) for details.

docs/guide/rpc-api.md

@@ -73,6 +73,7 @@ If the user denies the request, the Promise will reject with a `4001` error.
 
 The request causes a MetaMask popup to appear.
 You should only request the user's accounts in response to user action, such as a button click.
+You should always disable the button that caused the request to be dispatched, while the request is still pending.
 
 If you can't retrieve the user's account(s), you should encourage the user to initiate an account request.
 

docs/snippets/handleProvider.js

@@ -79,6 +79,10 @@ function handleAccountsChanged(accounts) {
 // to initiate the attempt.
 document.getElementById('connectButton', connect);
 
+// While you are awaiting the call to eth_requestAccounts, you should disable
+// any buttons the user can click to initiate the request.
+// MetaMask will reject any additional requests while the first is still
+// pending.
 function connect() {
   ethereum
     .request({ method: 'eth_requestAccounts' })