Fix broken xrefs (#1517)

* fix deploying and interacting

* fix pattern.adoc

* fix architecture.adoc

* fix dependencies.adoc

* fix mainnet.adoc

* fix public-staging.adoc

* fix on-upgrades.adoc

(cherry picked from commit 8bf20f7)

packages/cli/docs/modules/ROOT/pages/configuration.adoc

@@ -114,9 +114,9 @@ Any Solidity libraries used by the project's contracts are tracked in the `solid
 
 Another thing to notice in these files are the version numbers. The `<app-version>` keeps track of the latest app version, and matches `<version>` from `project.json`. The `<proxy-i-version>`, on the other hand, keeps track of which version of the contracts the proxies are pointing to. Say you deploy a contract in your app version 1.0.0, and then bump the version to 1.1.0 and push some upgraded code for that same contract. This will be reflected in the `<contract-i-address>`, but not yet in the proxy, which will display 1.0.0 in `<proxy-i-version>` and the old logic contract address in `<implementation-i-address>`. Once you run `oz update` to your contract, `<proxy-i-version>` will show the new 1.1.0 version, and `<implementation-i-address>` will point to the new `<contract-i-address>`. Note that this version identifier will refer to the version of the dependency (and not the app) if the proxy points to a dependent Ethereum Package.
 
-The field `<proxyAdmin>` contains the address of the ProxyAdmin contract, used to manage the xref:pattern.adoc#transparent-proxies-and-function-clashes[transparent proxy pattern] in the project's proxies.
+The field `<proxyAdmin>` contains the address of the ProxyAdmin contract, used to manage the xref:upgrades::proxies.adoc#transparent-proxies-and-function-clashes[transparent proxy pattern] in the project's proxies.
 
-Also, notice the fields `<app>`, `<package>`, and `<provider>`. These contain the addresses of contracts the OpenZeppelin CLI uses to facilitate the creation of proxies and the management of different versions of your contracts. These contracts will only be deployed once you `publish` your project to a desired network. That is, your project will not have an `app`, `package`, or `provider` unless explicitly running the `publish` command, or if the project was created with the `--publish` flag. Note that this step is required for projects that produce an Ethereum Package. To read more about the architecture of contracts we are using to publish your project on-chain please refer to the xref:architecture.adoc[Contract Architecture] section.
+Also, notice the fields `<app>`, `<package>`, and `<provider>`. These contain the addresses of contracts the OpenZeppelin CLI uses to facilitate the creation of proxies and the management of different versions of your contracts. These contracts will only be deployed once you `publish` your project to a desired network. That is, your project will not have an `app`, `package`, or `provider` unless explicitly running the `publish` command, or if the project was created with the `--publish` flag. Note that this step is required for projects that produce an Ethereum Package. To read more about the architecture of contracts we are using to publish your project on-chain please refer to the xref:contracts-architecture.adoc[Contract Architecture] section.
 
 Finally, the `dependencies` field stores information about linked Ethereum Packages. For each dependency, the `<dependency-address>` tracks the address of the deployed `package` in the network, and `<dependency-version>` is the exact semver identifier being used for the dependency. The `custom-deploy` field will be present only when a version of the Ethereum Package is deployed using the `--deploy-dependencies` flag of the `push` command, in which case `<custom-deploy>` will be `true`.
 

packages/cli/docs/modules/ROOT/pages/dependencies.adoc

@@ -40,7 +40,7 @@ NOTE: Make sure you install `@openzeppelin/contracts-ethereum-package` and not t
 [[creating-an-erc20-token]]
 == Creating an ERC20 Token
 
-Let's deploy an ERC20 token contract to our development network. Make sure to xref:learn::deploy-and-interact.adoc#local-blockchain[have a Ganache instance running], or start one by running:
+Let's deploy an ERC20 token contract to our development network. Make sure to xref:learn::deploying-and-interacting.adoc#local-blockchain[have a Ganache instance running], or start one by running:
 
 [source,console]
 ----
@@ -207,7 +207,7 @@ Success! We have our exchange up and running, gathering ETH in exchange for our
 
 We forgot to add a method to withdraw the funds from the token exchange contract! While this would typically mean that the funds are locked in there forever, we can upgrade the contract with the OpenZeppelin CLI to add a way to collect those funds.
 
-NOTE: While upgrading a contract is certainly useful in situations like this, where you need to fix a bug or add a missing feature, it could still be used to change the rules of the game. For instance, you could upgrade the token exchange contract to alter the rate at any time. Because of this, it is important to have a proper xref:learn::mainnet.adoc#project-governance[Project Governance] in place.
+NOTE: While upgrading a contract is certainly useful in situations like this, where you need to fix a bug or add a missing feature, it could still be used to change the rules of the game. For instance, you could upgrade the token exchange contract to alter the rate at any time. Because of this, it is important to have a proper xref:learn::preparing-for-mainnet.adoc#project-governance[Project Governance] in place.
 
 Let's modify the `TokenExchange` contract to add a `withdraw` method, only callable by an `owner`.
 

packages/cli/docs/modules/ROOT/pages/deploying-with-create2.adoc

@@ -8,7 +8,7 @@ In this guide we will precompute the address where a contract will be deployed a
 ====
 This guide features advanced usage of OpenZeppelin tools, and requires familiarity with Solidity, development blockchains and the OpenZeppelin CLI.
 
-For a refresher on the topics, head to xref:learn::deploy-and-interact.adoc[Deploying and Interacting With Smart Contracts].
+For a refresher on the topics, head to xref:learn::deploying-and-interacting.adoc[Deploying and Interacting With Smart Contracts].
 ====
 
 == Creating a Smart Contract

packages/cli/docs/modules/ROOT/pages/faq.adoc

@@ -49,7 +49,7 @@ However, if you are using OpenZeppelin Upgrades programmatically you could poten
 [[how-can-i-create-an-upgradeable-instance-from-solidity-code]]
 == How Can I Create an Upgradeable Instance From Solidity Code?
 
-You can create upgradeable instances from Solidity code by using your project's xref:contracts-architecture.adoc#app.sol[`App`] contract, and then calling its `create` function from Solidity. Note that to be able to do this, your project needs to be published, that is, it needs to have the OpenZeppelin xref:architecture.adoc[Contracts Architecture] enabled.
+You can create upgradeable instances from Solidity code by using your project's xref:contracts-architecture.adoc#app.sol[`App`] contract, and then calling its `create` function from Solidity. Note that to be able to do this, your project needs to be published, that is, it needs to have the OpenZeppelin xref:contracts-architecture.adoc[Contracts Architecture] enabled.
 
 To see an example of how this is done, please refer to the example project https://github.com/OpenZeppelin/openzeppelin-sdk/tree/master/examples/creating-instances-from-solidity[`creating-instances-from-solidity`].
 

packages/cli/docs/modules/ROOT/pages/getting-started.adoc

@@ -72,7 +72,7 @@ We will use https://truffleframework.com/ganache[Ganache] as a _development netw
 
 Development networks are mini blockchains that run just on your computer, and are much faster than the actual Ethereum network. We will use one for coding and testing.
 
-TIP: Head to xref:learn::deploy-and-interact.adoc#local-blockchain[Setting up a Local Blockchain] to learn more about using Ganache.
+TIP: Head to xref:learn::deploying-and-interacting.adoc#local-blockchain[Setting up a Local Blockchain] to learn more about using Ganache.
 
 Open a separate terminal and start a new Ganache process:
 

packages/cli/docs/modules/ROOT/pages/index.adoc

@@ -34,7 +34,7 @@ Below is a short list of the most used commands:
 == Learn More
 
  * Head to xref:getting-started.adoc[Getting Started] to see the CLI in action by deploying and upgrading a smart contract!
- * xref:using-dependencies.adoc[Using Dependencies] showcases a more complex project being built, including leveraging the xref:contracts::index.adoc[OpenZeppelin Contracts] library.
+ * xref:dependencies.adoc[Using Dependencies] showcases a more complex project being built, including leveraging the xref:contracts::index.adoc[OpenZeppelin Contracts] library.
  * If you are a Truffle user, go to xref:truffle.adoc[Using With Truffle] for information on using both tools on the same project.
  * Take a look at the API reference for all xref:commands.adoc[CLI commands].
  * For an overview of the internals of the CLI, you can read on the xref:contracts-architecture.adoc[Contracts Architecture] and different xref:configuration.adoc[Configuration Files].

packages/cli/docs/modules/ROOT/pages/publishing-ethereum-package.adoc

@@ -9,12 +9,12 @@ In this guide we'll describe how you can create your own Ethereum Package, and m
 ====
 This guide features advanced usage of OpenZeppelin tools, and requires familiarity with using public networks, upgradeable contracts, and the OpenZeppelin CLI.
 
-For a refresher on the topics, head to xref:learn::public-staging.adoc[Deploying to a Public Test Network] and xref:learn::on-upgrades.adoc[Upgrades].
+For a refresher on the topics, head to xref:learn::connecting-to-public-test-networks.adoc[Deploying to a Public Test Network] and xref:learn::upgrading-smart-contracts.adoc[Upgrades].
 ====
 
 == Storing Your Project On-chain
 
-So far, we've mostly limited ourselves to depoying contracts using xref:commands.adoc#create[`oz deploy`], which creates _upgradeable instances_ by deploying _proxies_ to an existing implementation contract (refer to xref:learn::on-upgrades.adoc#how-upgrades-work[How Upgrades Work] to brush up on this). Here, we will instead deploy just the implementations, so that other people can create new proxies pointing to them.
+So far, we've mostly limited ourselves to depoying contracts using xref:commands.adoc#create[`oz deploy`], which creates _upgradeable instances_ by deploying _proxies_ to an existing implementation contract (refer to xref:learn::upgrading-smart-contracts.adoc#how-upgrades-work[How Upgrades Work] to brush up on this). Here, we will instead deploy just the implementations, so that other people can create new proxies pointing to them.
 
 To achieve this, we'll use two low-level CLI commands: xref:commands.adoc#add[`oz add`] and xref:commands.adoc#push[`oz push`]. These work simmilarly to `git add` and `git push`: they will register contracts in your project and deploy them to a network.
 
@@ -34,7 +34,7 @@ $ npx oz push
 All contracts have been deployed
 ----
 
-NOTE: For your Ethereum Pacakge to be used by others, it needs to be deployed on a real network instead of a local one. Take a look at xref:learn::public-staging.adoc[Deploying to a Public Test Network] for detailed instructions for this process.
+NOTE: For your Ethereum Pacakge to be used by others, it needs to be deployed on a real network instead of a local one. Take a look at xref:learn::connecting-to-public-test-networks.adoc[Deploying to a Public Test Network] for detailed instructions for this process.
 
 Ethereum Packages are upgradeable, which means they track the different implementation contracts that correspond to each version of the package. We'll use the xref:commands.adoc#publish[`oz publish`] command for this, which will deploy an xref:contracts-architecture.adoc#app.sol[`App`] contract and register the implementations there:
 

packages/lib/docs/modules/ROOT/pages/creating-upgradeable-from-solidity.adoc

@@ -8,7 +8,7 @@ In this guide, we will learn how to create a contract https://en.wikipedia.org/w
 ====
 This guide features advanced usage of OpenZeppelin tools, and requires familiarity with Solidity, development blockchains and the OpenZeppelin CLI.
 
-For a refresher on the topics, head to xref:learn::deploy-and-interact.adoc[Deploying and Interacting With Smart Contracts].
+For a refresher on the topics, head to xref:learn::deploying-and-interacting.adoc[Deploying and Interacting With Smart Contracts].
 ====
 
 == Setting Up