R4R - Finish new docs v1 #5186

gamarin2 · 2019-10-11T14:53:38Z

This PR contains the last core docs we need for "new docs v1"

Targeted PR against correct branch (see CONTRIBUTING.md)
Linked to github-issue with discussion and accepted design OR link to spec that describes this work.
Wrote tests
Updated relevant documentation (docs/)
Added a relevant changelog entry to the Unreleased section in CHANGELOG.md
Re-reviewed Files changed in the github PR explorer

For Admin Use:

Added appropriate labels to PR (ex. wip, ready-for-review, docs)
Reviewers Assigned
Squashed all commits, uses message "Merge pull request #XYZ: [title]" (coding standards)

codecov · 2019-10-11T15:02:56Z

Codecov Report

Merging #5186 into master-docs will decrease coverage by 0.01%.
The diff coverage is n/a.

@@               Coverage Diff               @@
##           master-docs    #5186      +/-   ##
===============================================
- Coverage        54.85%   54.83%   -0.02%     
===============================================
  Files              305      305              
  Lines            18494    18494              
===============================================
- Hits             10144    10142       -2     
- Misses            7595     7597       +2     
  Partials           755      755

tac0turtle · 2019-10-12T17:00:12Z

docs/basics/accounts-fees-gas.md

+}
+```
+
+The default implementation of `Keybase` of the Cosmos SDK is [`dbKeybase`](https://github.com/cosmos/cosmos-sdk/blob/master/crypto/keys/keybase.go). A few notes on the `Keybase` methods as implemented in `dbKeybase`:


if the doc is moved in the future will it break these links?

well yes. We could use tags but the downside is that the link could become outdated instead of broken... Not sure one is better than the other (at least if it breaks we notice it)

but how will it affect releaes, i thought we will have versioned docs and this would break on some versions and not on others, and backporting shouldn't be something we do for docs, maybe a script on docs build for releases that changes master to a commit is needed?

yes that might be a good solution, would that be possible @fadeev?

If the goal is to substitute master with something else when necessary, we specify a variable in config.js and interpolate it into the URL {{version}}.

we should totally use permalinks here

If the goal is to substitute master with something else when necessary, we specify a variable in config.js and interpolate it into the URL {{version}}.

this will only work for SDK links. Everything else should use a permalink

I don't think we have permalinks for tendermint stuff, do we? @marbar3778

https://help.github.com/en/articles/getting-permanent-links-to-files, commit hashes

I don't think we need to worry about the repo disappearing case, there are bigger issues if that happens 🤣

tac0turtle · 2019-10-12T17:03:44Z

docs/basics/accounts-fees-gas.md

+
+`Addresses` and `PubKey`s are both public information that identify actors in the application. There are 3 main types of `Addresses`/`PubKeys` available by default in the Cosmos SDK:
+
+- Addresses and Keys for **accounts**, which identify users (e.g. the sender of a `message`). They are derived using the **`secp256k1`** curve. 


i believe with #5006 this isnt entirely true any more, you could use other keys, right @AdityaSripal ?

antedecorator will have a separate docs PR afaik. This pr should be based on this branch @AdityaSripal

tac0turtle · 2019-10-12T17:06:56Z

docs/core/events.md

+## Events
+
+`Event`s are implemented in the Cosmos SDK as an alias of the [ABCI `event` type](https://github.com/tendermint/tendermint/blob/master/abci/types/types.pb.go#L2661-L2667). They contain:


we shouldnt use master branch here, these will be moving soon, can we use a commit/tag instead?

@fadeev can we do the same thing with TM (i.e. variable interpolation via config.js)

fedekunze · 2019-10-16T13:20:30Z

docs/basics/accounts-fees-gas.md

+A `Keybase` is an object that stores and manages accounts. In the Cosmos SDK, a `Keybase` implementation follows the [`Keybase` interface](https://github.com/cosmos/cosmos-sdk/blob/master/crypto/keys/types.go#L14-L60):
+
+```go
+type Keybase interface {


@alessio will this change with the keyring PR?

fedekunze · 2019-10-16T13:21:45Z

docs/building-modules/genesis.md

use permalink

fedekunze · 2019-10-16T13:23:18Z

docs/core/encoding.md

+keeper.cdc.MustUnmarshalBinaryBare(bz, &object)
+```
+


typo uvarint

fedekunze · 2019-10-16T13:24:18Z

docs/core/node.md

+
+```go
+tmNode, err := node.NewNode(
+		cfg,


padding is off

fedekunze · 2019-10-16T13:24:32Z

docs/core/node.md

+```go
+if err := tmNode.Start(); err != nil {
+		return nil, err
+    }


padding is off

fedekunze · 2019-10-16T13:25:53Z

docs/core/node.md

+- First, a [`codec`](./encoding.md) is instanciated for the application.
+- Then, the [`config`](https://github.com/cosmos/cosmos-sdk/blob/master/types/config.go) is retrieved and config parameters are set. This mainly involves setting the bech32 prefixes for [addresses and pubkeys](../basics/accounts-fees-gas.md#addresses-and-pubkeys).
+- Using [cobra](https://github.com/spf13/cobra), the root command of the full-node client is created. After that, all the custom commands of the application are added using the `AddCommand()` method of `rootCmd`. 
+- Add default server commands to `rootCmd` using the `server.AddCommands(ctx, cdc, rootCmd, newApp, exportAppStateAndTMValidators)` method. These commands are separated from the ones added above since they are standard and defined at SDK level. They should be shared by all SDK-based application. They include the most important command: the [`start` command](#start-command).


Suggested change

- Add default server commands to `rootCmd` using the `server.AddCommands(ctx, cdc, rootCmd, newApp, exportAppStateAndTMValidators)` method. These commands are separated from the ones added above since they are standard and defined at SDK level. They should be shared by all SDK-based application. They include the most important command: the [`start` command](#start-command).

- Add default server commands to `rootCmd` using the `server.AddCommands(ctx, cdc, rootCmd, newApp, exportAppStateAndTMValidators)` method. These commands are separated from the ones added above since they are standard and defined at SDK level. They should be shared by all SDK-based applications. They include the most important command: the [`start` command](#start-command).

fedekunze · 2019-10-16T13:27:13Z

docs/core/store.md

+
+## Introduction to SDK Stores
+
+The Cosmos SDK comes with a large set of stores to persist the state of applications. By default, the main store of SDK applications is a multistore, i.e. a store of stores. Developers can add any number of key-value stores to the multistore, depending on their application needs. The multistore exists to support the modularity of the Cosmos SDK, as it lets each module declare and manage their own subset of the state. Key-value stores in the multistore can be accessed with a specific `key`, which is typically held in the [`keeper`](../building-modules/keeper.md) of the module that declared the store. 


this should mention that a StoreKey is really a capability key to access the store

fedekunze · 2019-10-16T13:27:49Z

docs/core/store.md

+Each Cosmos SDK application holds a multistore at its root to persist its state. The multistore is a store of `KVStores` that follows the `Multistore` interface:
+
+```go
+type MultiStore interface { //nolint


Suggested change

type MultiStore interface { //nolint

type MultiStore interface {

fedekunze · 2019-10-16T13:29:03Z

docs/basics/accounts-fees-gas.md

+}
+```
+
+The default implementation of `Keybase` of the Cosmos SDK is [`dbKeybase`](https://github.com/cosmos/cosmos-sdk/blob/master/crypto/keys/keybase.go). A few notes on the `Keybase` methods as implemented in `dbKeybase`:


If the goal is to substitute master with something else when necessary, we specify a variable in config.js and interpolate it into the URL {{version}}.

this will only work for SDK links. Everything else should use a permalink

hschoenburg · 2019-10-18T17:43:22Z

docs/core/node.md

+appd start
+```
+
+As a reminder, the full-node is composed of three conceptual layers: the networking layer, the consensus layer and the application layer. The first two are generally bundled together in an entity called the consensus engine, while the third is the state-machine defined with the help of the Cosmos SDK. Currently, the Cosmos SDK uses Tendermint as the default consensus engine, meaning the start command is implemented to boot up a Tendermint node. 


Suggested change

As a reminder, the full-node is composed of three conceptual layers: the networking layer, the consensus layer and the application layer. The first two are generally bundled together in an entity called the consensus engine, while the third is the state-machine defined with the help of the Cosmos SDK. Currently, the Cosmos SDK uses Tendermint as the default consensus engine, meaning the start command is implemented to boot up a Tendermint node.

As a reminder, the full-node is composed of three conceptual layers: the networking layer, the consensus layer and the application layer. The first two are generally bundled together in `Tendermint Core` while the third is the state-machine defined with the help of the Cosmos SDK.

"an entity call the consensus engine" is vaue, might want to specify Tendermint Core

hschoenburg · 2019-10-18T17:45:20Z

docs/core/node.md

+
+As a reminder, the full-node is composed of three conceptual layers: the networking layer, the consensus layer and the application layer. The first two are generally bundled together in an entity called the consensus engine, while the third is the state-machine defined with the help of the Cosmos SDK. Currently, the Cosmos SDK uses Tendermint as the default consensus engine, meaning the start command is implemented to boot up a Tendermint node. 
+
+The flow of the `start` command is pretty straightforward. First, it retrieves the `config` from the `context` in order to open the `db`. This `db` contains the latest known state of the application (empty if the application is started from the first time). 


the db is an instance of IAVL yes? maybe specify that? https://github.com/tendermint/iavl

nah it's a leveldb, I'll specify

hschoenburg · 2019-10-18T17:47:11Z

a few minor changes

hschoenburg

"Accounts Fees and Gas" is a heavily overloaded file. Why not split it into two? "Adresses and Accounts" & "Fees and Gas"

gamarin2 · 2019-10-21T12:46:48Z

@fedekunze @hschoenburg integrated your comments, please approve

tac0turtle

I think at this point this pr is blocked on getting a ci process to replace master with commit hashes, or has this already happened?

tac0turtle · 2019-10-23T10:08:59Z

docs/building-modules/handler.md

+		Events: ctx.EventManager().Events(),
+	}
+```
+
 For a deeper look at `handler`s, see this [example implementation of a `handler` function](https://github.com/cosmos/sdk-application-tutorial/blob/master/x/nameservice/handler.go) from the nameservice tutorial. 


this link will be broken in the coming days.

good job noticing that, I missed a few links. Added permalinks

should this be done for the sdk links as well? just thinking in terms of versioning

fadeev · 2019-10-23T10:21:05Z

@marbar3778 if you mean CI process of cosmos.network, then no, it's not blocking, we can merge into master safely.

https://allinbits.slack.com/archives/GDDLSDFPT/p1571509059077500

gamarin2 · 2019-10-23T10:24:00Z

Added permalinks, and no the CI process should not block this PR as denis said. If nothing else please approve 🙏

tac0turtle · 2019-10-23T10:46:29Z

ah I didn't mean that @fadeev meant a script to replace cosmos-sdk/blob/master with cosmos-sdk/blob/<commit_hash>

I think this script would have to be run on releases only though

gamarin2 added 8 commits September 17, 2019 17:38

working

9fa66e4

workin

036f418

Merge branch 'master-docs' into gamarin/finish-docs

7392275

encoding and node

c151b31

almost finish store

5ef23b0

merge

1d5d907

finish docs

7af02f8

fixes

2b419e9

gamarin2 added the T:Docs Changes and features related to documentation. label Oct 11, 2019

gamarin2 requested review from hschoenburg and jackzampolin October 11, 2019 14:53

gamarin2 requested review from alessio, alexanderbez, fedekunze and rigelrozanski as code owners October 11, 2019 14:53

gamarin2 changed the title ~~Finish docs v1~~ R4R - Finish new docs v1 Oct 11, 2019

fedekunze added the R4R label Oct 11, 2019

tac0turtle reviewed Oct 12, 2019

View reviewed changes

fedekunze suggested changes Oct 16, 2019

View reviewed changes

fede comments + permalinks

6ee28c4

hschoenburg approved these changes Oct 18, 2019

View reviewed changes

hschoenburg suggested changes Oct 18, 2019

View reviewed changes

hans review

e13a4bc

tac0turtle requested changes Oct 23, 2019

View reviewed changes

add more permalinks

1cc5c19

tac0turtle approved these changes Oct 23, 2019

View reviewed changes

gamarin2 merged commit 6d67876 into master-docs Oct 23, 2019

gamarin2 deleted the gamarin/finish-docs branch October 23, 2019 19:07

gamarin2 mentioned this pull request Dec 9, 2019

[R4R] New docs V1 (merge master-docs to master) #5379

Merged

11 tasks


		`Addresses` and `PubKey`s are both public information that identify actors in the application. There are 3 main types of `Addresses`/`PubKeys` available by default in the Cosmos SDK:

		- Addresses and Keys for accounts, which identify users (e.g. the sender of a `message`). They are derived using the `secp256k1` curve.

		## Events

		`Event`s are implemented in the Cosmos SDK as an alias of the [ABCI `event` type](https://github.com/tendermint/tendermint/blob/master/abci/types/types.pb.go#L2661-L2667). They contain:

	- Add default server commands to `rootCmd` using the `server.AddCommands(ctx, cdc, rootCmd, newApp, exportAppStateAndTMValidators)` method. These commands are separated from the ones added above since they are standard and defined at SDK level. They should be shared by all SDK-based application. They include the most important command: the [`start` command](#start-command).
	- Add default server commands to `rootCmd` using the `server.AddCommands(ctx, cdc, rootCmd, newApp, exportAppStateAndTMValidators)` method. These commands are separated from the ones added above since they are standard and defined at SDK level. They should be shared by all SDK-based applications. They include the most important command: the [`start` command](#start-command).


		## Introduction to SDK Stores

		The Cosmos SDK comes with a large set of stores to persist the state of applications. By default, the main store of SDK applications is a multistore, i.e. a store of stores. Developers can add any number of key-value stores to the multistore, depending on their application needs. The multistore exists to support the modularity of the Cosmos SDK, as it lets each module declare and manage their own subset of the state. Key-value stores in the multistore can be accessed with a specific `key`, which is typically held in the [`keeper`](../building-modules/keeper.md) of the module that declared the store.

	type MultiStore interface { //nolint
	type MultiStore interface {


		As a reminder, the full-node is composed of three conceptual layers: the networking layer, the consensus layer and the application layer. The first two are generally bundled together in an entity called the consensus engine, while the third is the state-machine defined with the help of the Cosmos SDK. Currently, the Cosmos SDK uses Tendermint as the default consensus engine, meaning the start command is implemented to boot up a Tendermint node.

		The flow of the `start` command is pretty straightforward. First, it retrieves the `config` from the `context` in order to open the `db`. This `db` contains the latest known state of the application (empty if the application is started from the first time).

		keeper.cdc.MustUnmarshalBinaryBare(bz, &object)
		```

R4R - Finish new docs v1 #5186

R4R - Finish new docs v1 #5186

Conversation

gamarin2 commented Oct 11, 2019

codecov bot commented Oct 11, 2019 • edited Loading

Codecov Report

Choose a reason for hiding this comment

gamarin2 Oct 14, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fadeev Oct 14, 2019 • edited Loading

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

tac0turtle Oct 16, 2019 • edited Loading

Choose a reason for hiding this comment

tac0turtle Oct 16, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tac0turtle Oct 12, 2019 • edited Loading

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hschoenburg commented Oct 18, 2019

hschoenburg left a comment

Choose a reason for hiding this comment

gamarin2 commented Oct 21, 2019

tac0turtle 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

fadeev commented Oct 23, 2019

gamarin2 commented Oct 23, 2019

tac0turtle commented Oct 23, 2019 • edited Loading

codecov bot commented Oct 11, 2019 •

edited

Loading

gamarin2 Oct 14, 2019 •

edited

Loading

fadeev Oct 14, 2019 •

edited

Loading

tac0turtle Oct 16, 2019 •

edited

Loading

tac0turtle Oct 16, 2019 •

edited

Loading

tac0turtle Oct 12, 2019 •

edited

Loading

tac0turtle commented Oct 23, 2019 •

edited

Loading