docs: restructure the docs website

packages/cli/README.md

@@ -47,7 +47,7 @@ push these contracts to a blockchain network with `zos push`, use
 `zos create` to create instances for these contracts that later can be
 upgraded, and many more things.
 
-Run `zos --help` for more details about thes and all the other functions of
+Run `zos --help` for more details about this and all the other functions of
 ZeppelinOS.
 
 The

packages/docs/docs/docs/advanced.md → packages/docs/docs/docs/configuration.md

@@ -1,119 +1,12 @@
 ---
-id: advanced
-title: Advanced topics
+id: configuration
+title: Configuration Files
 ---
 
-We expand on several advanced topics for the more intrepid users of ZeppelinOS.
-
-## Deploying to mainnet
-The [Building upgradeable applications](building.md) guide explains how to
-deploy an application to a local network, which is very good for testing.
-Once you are happy with your initial contracts, you can deploy them to mainnet
-using the `--network` flag.
-
-This flag takes the network details from the Truffle configuration file. You
-can use Infura to connect to mainnet, with a `truffle-config.js` like this one:
-
-```
-'use strict';
-
-var HDWalletProvider = require("truffle-hdwallet-provider");
-
-var mnemonic = "orange apple banana ... ";
-
-module.exports = {
-  networks: {
-    mainnet: {
-      provider: function() {
-        return new HDWalletProvider(mnemonic, "https://mainnet.infura.io/<INFURA_Access_Token>")
-      },
-      network_id: 1
-    }
-  }
-};
-```
-
-Make sure to replace the `mnemonic` with the one you used to generate your
-accounts, and change `<INFURA_Access_Token>` to your token.
-
-Install the `truffle-hdwallet-provider` module with:
-
-```
-npm install truffle-hdwallet-provider
-```
-
-And now you can run `zos` commands in mainnet. For example:
-
-```
-zos push --network mainnet
-```
-
-This will use your first account generated from the mnemonic. If you want to
-specify a different account, use the `--from` flag.
-
-Here you will find a
-[guide with more details about configuring Truffle to use Infura](http://truffleframework.com/tutorials/using-infura-custom-provider).
-You can use other test networks like ropsten to further test your contracts
-before pushing them to mainnet. But remember that now your contracts are
-upgradeable! Even if you find a bug after deploying them to mainnet, you will
-be able to fix it without losing the contract state and in a way that's
-transparent for your users.
-
-#### Calling Initialize Functions Manually in Your Unit Tests
-
-Truffle does not know how to resolve situations where a contract has functions that have matching names, but different arities. Here's an example of a `TimedCrowdsale` contract that inherits from `Crowdsale` which results in a contract that has two `initialize` functions with different arities:
-
-```
-contract TimedCrowdsale is Crowdsale {
-
-  initialize(uint256 _openingTime, uint256 _closingTime)
-    public
-    isInitializer("TimedCrowdsale", "0.0.1")
-  {
-    Crowdsale.initialize(_rate, _wallet, _token);
-  }
-}
-
-contract Crowdsale {
-
-  initialize(uint256 _rate, address _wallet, ERC20 _token)
-    public
-    isInitializer("Crowdsale", "0.0.1")
-  {
-    // does something
-  }
-}
-```
-
-This means that calls to contracts with more than one function named `initialize`, as is the case with some contracts from OpenZeppelin (e.g., TimedCrowdsale), may revert if you call `initialize` directly from Truffle. `zos create` handles this correctly as it encodes the parameters. However, for your unit tests you will need to call `initialize` manually.
-
-The current solution to this issue is to `npm install zos-lib` and use the same helper function `zos create` uses: `encodeCall`. `encodeCall` receives the signature of your `initialize` function, as well as its arguments and their types. It then crafts the calldata which you can send in a raw call. Here's an example:
-
-```
-data = encodeCall(
-    "initialize",
-    ['address', 'string', 'string', 'uint8', 'address'],
-    [owner, name, symbol, decimals, exampleToken.address]
-);
-
-await exampleToken.sendTransaction( {data, from: owner} );
-```
-## Safety checks
-
-The ZeppelinOS CLI performs a series of safety checks in some of its commands with the purpose of strengthening the security of your projects. For example, the `zos add` command can detect if a contract has a `constructor`, or contains usages of `selfdestruct` or `delegatecall`. Below is a list of some of the checks made, along with the reasoning behind why they are considered to be security risks.
-
-**Some validation examples:**
-* constructor check: Proxied contracts should use initializer functions instead of constructors. For more info, see [Initializers vs. constructors](https://docs.zeppelinos.org/docs/advanced.html#initializers-vs-constructors) in this page.
-* selfdestruct check: Solidity's `selfdestruct` keyword ends the execution of a contract, destroys it, and sends all of its funds to a specified account. This is a very delicate action to take, and can expose a contract to vulnerabilities such as the [second Parity Wallet hack](https://blog.zeppelinos.org/parity-wallet-hack-reloaded/). It should be used with extreme care.
-* delegatecall check: The `delegatecall` keyword fully exposes a contract's state to a 3rd party contract. Such a contract has complete control on the calling contract. It should only be used if you really know [hat you're doing.
-
-When such validation checks fail, the ZeppelinOS CLI will not performs any actions unless the `--force` option is used. If so, the CLI will perform the actions and try to remember your choice in future occasions.
-
-## Format of `zos.json` and `zos.<network>.json` files
 ZeppelinOS's CLI generates `json` files where it stores the configuration of your project.
 
 
-### `zos.json`
+## `zos.json`
 The first file stores the general configuration and is created by the `zos init` command. It has the following structure:
 
 ```json
@@ -132,10 +25,10 @@ The first file stores the general configuration and is created by the `zos init`
 }
 ```
 
-Here, `<projectName>` is the name of the project, and `<version>` is the current version number. Once you start adding your contracts via `zos add`, they will be recorded under the `"contracts"` field, with the contract aliases as the keys (which default to the contract names), and the contract names as the values. Finally, if you link an `stdlib` with `zos link`, this will be reflected in the `"stdlib"` field, where `<stdlibName>` is the name of the linked `EVM package`.
+Here, `<projectName>` is the name of the project, and `<version>` is the current version number. Once you start adding your contracts via `zos add`, they will be recorded under the `"contracts"` field, with the contract aliases as the keys (which default to the contract names), and the contract names as the values. Finally, if you link an `stdlib` with `zos link`, this will be reflected in the `"stdlib"` field, where `<stdlibName>` is the name of the linked `EVM Package`.
 
 
-### `zos.<network>.json`
+## `zos.<network>.json`
 ZeppelinOS will also generate a file for each of the networks you work on (`local`, `ropsten`, `live`, ... These should be configured [in your `truffle.js` file](http://truffleframework.com/docs/advanced/configuration#networks), but note that `zos init` already configures the `local` network, which can be run by `npx truffle develop`). These files share the same structure:
 
 ```json
@@ -203,4 +96,5 @@ Another thing to notice in these files are the version numbers. The `<appVersion
 
 Also, notice the fields `<app>` and `<package>`. These contain the addresses of contracts that ZeppelinOS 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` or `package` unless explicitly running the `publish` command. Note that this step is required for projects that produce an EVM package. To read more about the architecture of contracts we are using to publish your project on-chain please refer to the [Contract Architecture](https://docs.zeppelinos.org/docs/architecture.html) section.
 
+
 Finally, the `stdlib` field stores information about linked EVM packages. Its address is stored in `<stdlib-address>`, and its name in `<stdlib-name>`, matching that in `zos.json`. The `custom-deploy` field will be present only when a version of the EVM package is deployed using the `--deploy-libs` flag of the `push` command, in which case `<custom-deploy>` will be `true`. The remaining addresses, `<app-address>`, `<package-address>`, and `<provider-address>` store the addresses of the `App`, the `Package`, and the current `ImplementationProvider` respectively.

packages/docs/docs/docs/deploying.md

@@ -0,0 +1,129 @@
+---
+id: deploying
+title: Deploying your first project
+---
+
+The following steps will get you started using ZeppelinOS.
+
+## Installation
+
+Let's install [Node.js](http://nodejs.org/) and
+[npm](https://npmjs.com/), which are the dependencies to get started. On their
+respective websites you will find specific instructions for your machine.
+
+Then, install ZeppelinOS running:
+
+```sh
+npm install --global zos
+```
+
+Run `zos --help` to get a list of all the ZeppelinOS commands. At any time
+during this guides when we introduce a new command, run
+`zos <command-name> --help` to get more information about that command and
+its arguments.
+
+## Setting up your project
+
+We'll need to create a directory for our project and access it:
+
+```sh
+mkdir my-project
+cd my-project
+```
+
+Use `npm` to create a `package.json` file:
+
+```sh
+npm init
+```
+
+This command will ask you for details about the project. For this very basic
+guide you can just press enter to accept the default values of each field.
+
+Now, we can initialize the ZeppelinOS project:
+
+```
+zos init my-project
+```
+
+This command will create a `zos.json` file, which contains all the information
+about the project. For details about this file format, please see the
+[configuration files](configuration.md#zosjson) page.
+
+The command will also initialize [Truffle](https://truffleframework.com/), so
+by now, inside the `my-project` directory you should have a `package.json` file
+(create by `npm`), two empty directories named `contracts` and `migrations` and
+a file `truffle-config.js` (created by `zos` for Truffle), and a file
+`zos.json` (created by `zos` for ZeppelinOS).
+
+## Adding a contract
+
+Let's create a very simple contract as an example to be added to the project.
+Name it `MyContract.sol`, and put it in the `contracts/` folder with the
+following Solidity code:
+
+```sol
+pragma solidity ^0.4.24;
+
+import "zos-lib/contracts/Initializable.sol";
+
+contract MyContract is Initializable {
+
+  uint256 public x;
+
+  function initialize(uint256 _x) initializer public {
+    x = _x;
+  }
+}
+```
+
+Notice that our sample contract has an `initialize` function instead of the
+standard Solidity constructor. This is required by ZeppelinOS if you want to
+upgrade your contract later, which we'll see in more detail in the next
+guide.
+
+But before we get there, we still need a couple of steps. This contract
+imports another contract from the `zos-lib` package, so we have to install it:
+
+```
+npm install zos-lib
+```
+
+Now we can add the contract to the project:
+
+```sh
+zos add MyContract
+```
+
+This command will first compile `MyContract`, and then it will add it to the
+project writing it in the `zos.json` configuration file.
+
+## Deploying your project
+
+And just like that, we are now ready to make the initial deployment of the
+project. We are just missing a blockchain network where it will be deployed.
+For this example, let's use Truffle's local development network. To start it,
+open a separate terminal and run:
+
+```sh
+truffle develop --network local
+```
+
+And back in the original terminal:
+
+```sh
+NODE_ENV=test zos push --network local
+```
+
+This creates a `zos.local.json` file with all the information about your
+project in this specific network. You can read more about this file format
+in the [configuration files](configuration.md#zos-network-json) section.
+
+You can follow the same steps to deploy your project to mainnet or other test
+networks by just replacing `local` with the network name from your
+`truffle-config.js` file, and removing the `NODE_ENV=test` flag. This is
+further explained in the [Deploying to mainnet](mainnet) guide.
+
+But for now, let's continue exploring the ZeppelinOS features! The initial
+version of our project exists in the blockchain. Next, we will learn how to
+upgrade it.