testnet readme usability overhaul #1212

nylira · 2018-06-12T05:53:25Z

codecov · 2018-06-12T06:04:13Z

Codecov Report

Merging #1212 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #1212   +/-   ##
=======================================
  Coverage   60.87%   60.87%           
=======================================
  Files          89       89           
  Lines        4368     4368           
=======================================
  Hits         2659     2659           
  Misses       1539     1539           
  Partials      170      170

ValarDragon

Great job, These changes make it way better!
I added a few minor suggestions.

ValarDragon · 2018-06-12T07:19:46Z

cmd/gaia/testnets/README.md

-The last step is the adjust the `$HOME/.gaiad/config/config.toml`. Make sure that you are connected to healthy peers or seed nodes.
-These are some seeds nodes and they can be put into the config under the `seeds` key. Alternatively you can also
-ask user validators directly for a persistent peer and add it under the `persisent_peers` key.
+The last step is to update the `$HOME/.gaiad/config/config.toml`. Make sure that you are connected to healthy peers or seed nodes. These are some seeds nodes and they can be put into the config under the `seeds` key. You can also ask other validators for a persistent peer and add it under the `persisent_peers` key.


I'd recommend adding "See here" for more info on seed nodes and persistent peers. (Just to give people knowledge that more docs exist)

I will add this!

ValarDragon · 2018-06-12T07:22:27Z

cmd/gaia/testnets/README.md


 ```
 MYADDR=<your_newly_generated_address>
 MYPUBKEY=<your_newly_generated_public_key>
 ```

-**IMPORTANT:** We strongly recommend to **NOT** use the same passphrase for your different keys. The Tendermint team and the Interchain Foundation will not be responsible for the lost of funds.
+**IMPORTANT:** We strongly recommend **NOT** using the same passphrase for all your keys. The Tendermint team and the Interchain Foundation will not be responsible for the loss of funds.


minor nitpick, but perhaps "multiple keys" would be better suited than "all your keys"

Sounds good!

should we add an example of address? since we change it to bech32 encode. it will look so different

ValarDragon · 2018-06-12T07:24:15Z

cmd/gaia/testnets/README.md


-The best way to get coins at the moment is to ask in Riot chat. We plan to have a reliable faucet in future testnets.
+The best way to get tokens is from the [Cosmos Testnet Faucet](https://faucetcosmos.network). If the faucet is not working for you, try asking [#cosmos-validators](https://riot.im/app/#/room/#cosmos-validators:matrix.org).


May also want to add, "if you were a validator on previous testnets, you can submit a PR to add yourself to the next genesis file, no guarantees that it will get accepted though. We're currently working on tooling to make this more easy."

This section is being added by Zaki's PR here: #1211

Cool! Didn't see that

ValarDragon · 2018-06-12T07:24:54Z

cmd/gaia/testnets/README.md


-The `--sequence` flag corresponds to the sequence number to sign the tx.


I think it is still valuable to show that sequence numbers are a thing. Just add a line afterwards saying that if the sequence flag is omitted, it will auto-increment.

From a usability standpoint, this readme is not documentation for gaiacli. My goal with these changes is to simplify onboarding for full nodes and validators. From what I can tell, the --sequence is no longer required for any command, so it's best to omit it. That's one less feature users have to worry about so they can focus on other things.

We should have comprehensive gaiacli and gaiad docs in another file (that covers the sequence flag).

ValarDragon · 2018-06-12T07:28:51Z

cmd/gaia/testnets/README.md

-Follow these instructions to install the Cosmos-SDK and connect to the latest Testnet. This instructions work for both a local machine and a VM in a cloud server.
-
-If you want to run a non-validator full-node, installing the SDK on a Cloud server is a good option. However, if you are want to become a validator for the Hub's `mainnet` you should look at more complex setups, including [Sentry Node Architecture](https://github.com/cosmos/cosmos/blob/master/VALIDATORS_FAQ.md#how-can-validators-protect-themselves-from-denial-of-service-attacks), to protect your node from DDOS and ensure high-availability (see the [technical requirements](https://github.com/cosmos/cosmos/blob/master/VALIDATORS_FAQ.md#technical-requirements)). You can find more information on validators in our [website](https://cosmos.network/validators), in the [Validator FAQ](https://cosmos.network/resources/validator-faq) and in the [Validator Chat](https://riot.im/app/#/room/#cosmos_validators:matrix.org).
+## Installing Software



You may want to consider linking to https://github.com/cosmos/cosmos-sdk/blob/rigel/spec-staking/docs/guides/sdk/install.md for how to install / or link to the ubuntu/bsd installation scripts provided in that link, since those are the easiest way for people to get started. (To reduce the amount of documentation duplication)

kwunyeung

Suggest to have panic error message mentioned.

kwunyeung · 2018-06-12T07:38:52Z

cmd/gaia/testnets/README.md


 ```
 gaiacli keys show <your_key_name>
 ```

-You can see all your other available keys by typing:
+You can see all your available keys by typing:

 ```
 gaiacli keys list
 ```



Usually, newly joining validators would query their accounts right after they create the key and they all ask about the panic error message. Better add this and let them have expectation on seeing this rather than keep asking every time.

The panic is fixed in the latest version of gaiad!

Oh sorry. Didn't notice this.

Just tried and it becomes an error message.

Would it be still good to put the error message in? I think most users don't know what's happening with this.

ERROR: Error{1:9,--= Error =--
Message: No account with address cosmosaccaddr14c830n7ew3awdk4n770j9ckw3x4dlj6nwfd0ne was found in the state.
Are you sure there has been a transaction involving it?
Cause: <nil>
T: 0x9
Msg Traces:
--= /Error =--
}

Yeah, I'll put a section of that error message in the readme

ValarDragon · 2018-06-12T07:56:58Z

cmd/gaia/testnets/README.md

+gaiacli account <your_newly_generated_address>
+```
+
+Note: If you query your account before any tokens have been sent to it, you will see a `panic` error. This error is expected! We are working on improving error messages.


But this is fixed in the current version. (v0.18.0 has the fix)

Ah ok! Good to know.

kidinamoto01 · 2018-06-12T08:38:22Z

cmd/gaia/testnets/README.md


 ```
 gaiacli status
 ```

-## Generate keys
+View the status of the network with the [Cosmos Explorer](https://explorecosmos.network).Once your full node syncs up to the current block height, you should see it appear on the [list of full nodes](https://explorecosmos.network/validators).


I thinks it's hard to see your node in this explorer because the number of connections is limited

add link to official faucet, remove sequence from cmds readme improvements wording improvements and simplifications add link to cosmos explorer remove instances of candidate add apostrophe small fixes improve the installing software section fixes based on feedback add note about querying an empty account remove panic note update introduction add full cp path for copying genesis.json update moniker warning remove redundant sections add error message when querying empty account don't need a link to golang.org link to sections, better section names fix section link reorganize sections add h3s remove & symbol add whitespace update h3 to h2 add note about explorer not connecting to every node

zmanian · 2018-06-12T13:43:31Z

cmd/gaia/testnets/README.md


 ```
-export GOPATH=$HOME/go
-export PATH=$PATH:$GOROOT/bin:$GOPATH/bin
+go get github.com/cosmos/cosmos-sdk


Some users have reported that go doesn't checkout the directory/deletes it b/c of the lack buildable top level go files.

Haven't really reproduced this.

I've experienced something similar before. go get does checkout the directory and clones all the files, it just gives you a warning that there are no top level go files in that repo.

I think we should stop suggesting go get ever and just always do the full mkdir and git clone

ebuchman

Awesome, thanks - I'll pick up my comments and merge

ebuchman · 2018-06-13T03:10:29Z

cmd/gaia/testnets/README.md


 ```
-export GOPATH=$HOME/go
-export PATH=$PATH:$GOROOT/bin:$GOPATH/bin
+go get github.com/cosmos/cosmos-sdk


I think we should stop suggesting go get ever and just always do the full mkdir and git clone

ebuchman · 2018-06-13T03:17:34Z

cmd/gaia/testnets/README.md

 ```

-## Full Node Setup
+Your node is now in a pristine state while keeping the original `priv_validator.json`. If you had any sentry nodes or full nodes setup before, they should continue to work.


this preserves the config. the seeds/persistent-peers in the config will also need to upgrade if we're going to be able to connect with them

ebuchman · 2018-06-13T03:58:18Z

cmd/gaia/testnets/README.md


-You can delegate \(_i.e._ bind\) **Atoms** to a validator to become a [delegator](https://cosmos.network/resources/delegators) and obtain a part of its fee revenue in **Photons**. For more information about the Cosmos Token Model, refer to our [whitepaper](https://github.com/cosmos/cosmos/raw/master/Cosmos_Token_Model.pdf).
+On the upcoming mainnet, you can delegate `atom` to a validator. These [delegators](https://cosmos.network/resources/delegators) can receive part of the validator's fee revenue in `photon`. Read more more about the [Cosmos Token Model](https://github.com/cosmos/cosmos/raw/master/Cosmos_Token_Model.pdf).


"fee revenue". no need to mention photon

* Update joining testnet docs * Fix script errors * Fix unverified commit * Make requested changes * Update peer & rpc values to point to testnet docs * Update testnet repo link * Make requested changes * Fix instructions * Update vega upgrade info Co-authored-by: billy rennekamp <[email protected]>

nylira requested a review from ebuchman as a code owner June 12, 2018 05:53

nylira mentioned this pull request Jun 12, 2018

Add link to official faucet cosmos/testnets#54

Closed

nylira changed the title ~~testnet readme - add link to official faucet, remove sequence from cmds~~ testnet readme usability overhaul Jun 12, 2018

nylira mentioned this pull request Jun 12, 2018

"gaiacli stake create-validator" example contains wrong flag (--address-candidate) cosmos/testnets#52

Closed

ValarDragon reviewed Jun 12, 2018

View reviewed changes

kwunyeung reviewed Jun 12, 2018

View reviewed changes

ValarDragon reviewed Jun 12, 2018

View reviewed changes

kidinamoto01 reviewed Jun 12, 2018

View reviewed changes

nylira force-pushed the peng/add-faucet-rm-sequence branch from 3b44f97 to 3b9cb49 Compare June 12, 2018 08:54

zmanian reviewed Jun 12, 2018

View reviewed changes

jbibla mentioned this pull request Jun 12, 2018

gaia ux and guide improvements proposal #1223

Closed

ebuchman reviewed Jun 13, 2018

View reviewed changes

ebuchman merged commit 8e2a317 into master Jun 13, 2018

ebuchman deleted the peng/add-faucet-rm-sequence branch June 13, 2018 04:05

testnets: minor readme update

a03770d

nylira mentioned this pull request Jun 13, 2018

Add directory changes to instructions #1209

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

testnet readme usability overhaul #1212

testnet readme usability overhaul #1212

nylira commented Jun 12, 2018 •

edited

Loading

codecov bot commented Jun 12, 2018 •

edited

Loading

ValarDragon left a comment

ValarDragon Jun 12, 2018

nylira Jun 12, 2018

ValarDragon Jun 12, 2018

nylira Jun 12, 2018

kidinamoto01 Jun 12, 2018

ValarDragon Jun 12, 2018

nylira Jun 12, 2018

ValarDragon Jun 12, 2018

ValarDragon Jun 12, 2018

nylira Jun 12, 2018 •

edited

Loading

ValarDragon Jun 12, 2018

kwunyeung left a comment

kwunyeung Jun 12, 2018

ValarDragon Jun 12, 2018

kwunyeung Jun 12, 2018

kwunyeung Jun 12, 2018

nylira Jun 12, 2018

ValarDragon Jun 12, 2018

nylira Jun 12, 2018

kidinamoto01 Jun 12, 2018

nylira Jun 12, 2018

zmanian Jun 12, 2018

nylira Jun 12, 2018

ebuchman Jun 13, 2018

ebuchman left a comment

ebuchman Jun 13, 2018

ebuchman Jun 13, 2018

ebuchman Jun 13, 2018


		The best way to get coins at the moment is to ask in Riot chat. We plan to have a reliable faucet in future testnets.
		The best way to get tokens is from the [Cosmos Testnet Faucet](https://faucetcosmos.network). If the faucet is not working for you, try asking [#cosmos-validators](https://riot.im/app/#/room/#cosmos-validators:matrix.org).


		The `--sequence` flag corresponds to the sequence number to sign the tx.


		You can delegate \(_i.e._ bind\) Atoms to a validator to become a [delegator](https://cosmos.network/resources/delegators) and obtain a part of its fee revenue in Photons. For more information about the Cosmos Token Model, refer to our [whitepaper](https://github.com/cosmos/cosmos/raw/master/Cosmos_Token_Model.pdf).
		On the upcoming mainnet, you can delegate `atom` to a validator. These [delegators](https://cosmos.network/resources/delegators) can receive part of the validator's fee revenue in `photon`. Read more more about the [Cosmos Token Model](https://github.com/cosmos/cosmos/raw/master/Cosmos_Token_Model.pdf).

testnet readme usability overhaul #1212

testnet readme usability overhaul #1212

Conversation

nylira commented Jun 12, 2018 • edited Loading

codecov bot commented Jun 12, 2018 • edited Loading

Codecov Report

ValarDragon left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nylira Jun 12, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kwunyeung left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ebuchman left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nylira commented Jun 12, 2018 •

edited

Loading

codecov bot commented Jun 12, 2018 •

edited

Loading

nylira Jun 12, 2018 •

edited

Loading