docs: cleanups and consolidation. #239
Conversation
README.md
Outdated
| for extending the feature-set of the cryptocurrency by implementing plugins. | ||
|
|
||
| This SDK affords you all the tools you need to rapidly develop | ||
| robust blockchains and blockchain applications which are interoperable with The | ||
| Cosmos Hub. It is a blockchain development 'starter-pack' of common blockchain |
There was a problem hiding this comment.
Hahah, starter pack, this is a great tribute, for posterity, about our society's current communication style
There was a problem hiding this comment.
docs/overview.md
Outdated
| uniquely by each application. From the multiple layers of tx, each middleware | ||
| may strip off one level, like an onion. As such, the transaction must be | ||
| constructed to mirror the execution stack, and each middleware module should | ||
| allow embedding an arbitrary tx for the next layer in the stack. |
There was a problem hiding this comment.
This paragraph is nice, I initially struggled to understand why we had all these middleware, this paragraph reminds me of the clarity I got after @ethanfrey explained the concept to me a few times, while we were working on basecoin.
docs/overview.md
Outdated
|
|
||
| <img src="https://github.com/tendermint/basecoin/blob/unstable/docs/graphics/tx.png" width=250> | ||
| <img src="..//graphics/tx.png" width=250> |
There was a problem hiding this comment.
I think we wanna use "./graphics/tx.png" instead.
Also do we have the graphics directory in the root of the repo yet?
There was a problem hiding this comment.
the extra slash is a typo and the .. was before moving the files out of the old quark directory. The root of repo doesn't have a graphics dir & I don't think it needs one.
README.md
Outdated
| @@ -13,9 +13,17 @@ Branch | Tests | Coverage | Report Card | |||
| develop | [](https://circleci.com/gh/cosmos/cosmos-sdk/tree/develop) | [](https://codecov.io/gh/cosmos/cosmos-sdk) | [](https://goreportcard.com/report/github.com/cosmos/cosmos-sdk/tree/develop) | |||
| master | [](https://circleci.com/gh/cosmos/cosmos-sdk/tree/master) | [](https://codecov.io/gh/cosmos/cosmos-sdk) | [](https://goreportcard.com/report/github.com/cosmos/cosmos-sdk/tree/master) | |||
|
|
|||
| The Cosmos SDK is an [ABCI application](https://github.com/tendermint/abci) designed to be used with the [Tendermint consensus engine](https://tendermint.com/) to form a Proof-of-Stake cryptocurrency. It also provides a general purpose framework | |||
| The Cosmos SDK is the core framework for constructing | |||
| the atom tokens which will power [The Cosmos Network](https://cosmos.network/). It is an [ABCI application](https://github.com/tendermint/abci) designed to be used with the [Tendermint consensus engine](https://tendermint.com/) to form a Proof-of-Stake cryptocurrency. It also provides a general purpose framework | |||
There was a problem hiding this comment.
The cosmos-sdk is not used to construct the atom tokens. It is used to build the cosmos hub, which is the cryptocurrency for atoms. The cosmos hub is the blockchain.
There was a problem hiding this comment.
The sdk is the middleware platform which the hub is constructed from. The hub is a blockchain (or internet of blockchains) which the atom supply resides in. The atom supply is defined at genesis and can change based on the rules of the hub
README.md
Outdated
| Cosmos Hub. It is a blockchain development 'starter-pack' of common blockchain | ||
| modules while not enforcing their use thus giving maximum flexibility for | ||
| application customization. For example, do you require fees, how do you | ||
| want to log messages, do you enable IBC, do you even have a cryptocurrency? |
There was a problem hiding this comment.
Example: It is the Rails of cryptocurrencies.
| @@ -1,6 +1,6 @@ | |||
| # Cosmos SDK | |||
|
|
|||
|  | |||
|  | |||
There was a problem hiding this comment.
moved the image for less clutter in root of repo
docs/overview.md
Outdated
| mirror the execution stack, and each middleware should allow embedding an | ||
| arbitrary tx for the next layer in the stack. | ||
| Each transaction passes through the middleware stack which can be defined | ||
| uniquely by each application. From the multiple layers of tx, each middleware |
There was a problem hiding this comment.
Has the acronym tx already been introduced before you use it in a sentence? I would be tempted to be put it right in the paragraph header aka ### Transaction (tx)
There was a problem hiding this comment.
there was an attempt to s/tx/transaction/g for readability, didn't catch them all
docs/overview.md
Outdated
| uniquely by each application. From the multiple layers of tx, each middleware | ||
| may strip off one level, like an onion. As such, the transaction must be | ||
| constructed to mirror the execution stack, and each middleware module should | ||
| allow embedding an arbitrary tx for the next layer in the stack. |
There was a problem hiding this comment.
"allow an arbitrary tx to be embedded.. "
README.md
Outdated
| @@ -13,9 +13,19 @@ Branch | Tests | Coverage | Report Card | |||
| develop | [](https://circleci.com/gh/cosmos/cosmos-sdk/tree/develop) | [](https://codecov.io/gh/cosmos/cosmos-sdk) | [](https://goreportcard.com/report/github.com/cosmos/cosmos-sdk/tree/develop) | |||
| master | [](https://circleci.com/gh/cosmos/cosmos-sdk/tree/master) | [](https://codecov.io/gh/cosmos/cosmos-sdk) | [](https://goreportcard.com/report/github.com/cosmos/cosmos-sdk/tree/master) | |||
|
|
|||
| The Cosmos SDK is an [ABCI application](https://github.com/tendermint/abci) designed to be used with the [Tendermint consensus engine](https://tendermint.com/) to form a Proof-of-Stake cryptocurrency. It also provides a general purpose framework | |||
| The Cosmos SDK is the middleware platform which the [Cosmos](https://cosmos.network) HUB is constructed from. The HUB is a blockchain (or, internet of blockchains) in which the atom supply resides. The atos supply is defined at genesis and can change based on the rules of the HUB. | |||
There was a problem hiding this comment.
I'm don't think that HUB should be all capitalized, it is not an acronym (unlike SDK which is). Please use Cosmos Hub throughout unless there's a major objection or something I'm unaware of
There was a problem hiding this comment.
👍 (not sure why I capitalized...)
README.md
Outdated
| @@ -13,9 +13,19 @@ Branch | Tests | Coverage | Report Card | |||
| develop | [](https://circleci.com/gh/cosmos/cosmos-sdk/tree/develop) | [](https://codecov.io/gh/cosmos/cosmos-sdk) | [](https://goreportcard.com/report/github.com/cosmos/cosmos-sdk/tree/develop) | |||
| master | [](https://circleci.com/gh/cosmos/cosmos-sdk/tree/master) | [](https://codecov.io/gh/cosmos/cosmos-sdk) | [](https://goreportcard.com/report/github.com/cosmos/cosmos-sdk/tree/master) | |||
|
|
|||
| The Cosmos SDK is an [ABCI application](https://github.com/tendermint/abci) designed to be used with the [Tendermint consensus engine](https://tendermint.com/) to form a Proof-of-Stake cryptocurrency. It also provides a general purpose framework | |||
| The Cosmos SDK is the middleware platform which the [Cosmos](https://cosmos.network) HUB is constructed from. The HUB is a blockchain (or, internet of blockchains) in which the atom supply resides. The atos supply is defined at genesis and can change based on the rules of the HUB. | |||
There was a problem hiding this comment.
typo: atos -> Atoms (I believe we should capitalize Atom and Atoms, see this link https://www.quora.com/When-should-the-word-bitcoin-be-capitalized)
docs/glossary.md
Outdated
| inspect the chain. | ||
| in the basecoin root package, and all modules can register their own transaction | ||
| types there. This allows us to deserialize the entire transaction in one location | ||
| (even with types defined in other repos), to easily embed an arbitrary tx inside |
There was a problem hiding this comment.
If you are removing the use of 'tx' in text (which I agree with and it looks like you are) then you missed one on this line
docs/glossary.md
Outdated
| types there. This allows us to deserialize the entire transaction in one location | ||
| (even with types defined in other repos), to easily embed an arbitrary tx inside | ||
| another without specifying the type, and provide an automatic json representation | ||
| to provide to users (or apps) to inspect the chain. |
There was a problem hiding this comment.
the word 'provide' used too many times... how about "provide an automatic json representation allowing for users (or apps) to inspect the chain."
docs/glossary.md
Outdated
| make sure the correct transactions get to the correct module. So we have have | ||
| `coin` sending money, `roles` creating multi-sig accounts, and `ibc` following | ||
| other chains all working together without interference. | ||
| make sure the correct transactions get to the correct module. So we have the |
There was a problem hiding this comment.
remove "the" from "So we have the..."
docs/overview.md
Outdated
|
|
||
| ### Execution Stack | ||
|
|
||
| Middleware components allow for code reusability and integrability. A standard | ||
| set of middleware are provided and can be mix-and-matched with custom | ||
| middleware. Some of the [standard | ||
| library](https://github.com/tendermint/basecoin/blob/unstable/docs/quark/stdlib.md) | ||
| middleware. Some of the [standardlibrary](stdlib.md) |
There was a problem hiding this comment.
missing space in "standardlibrary"
docs/overview.md
Outdated
| state-recovery points (checkpoints) can be assigned for stack execution of | ||
| `CheckTx` or `DeliverTx`. This means, that all state changes will be reverted | ||
| to the checkpoint state on failure when either being run as a part of `CheckTx` | ||
| state-recovery check-points can be assigned for stack execution of `CheckTx` |
There was a problem hiding this comment.
check-points -> checkpoints
docs/overview.md
Outdated
|
|
||
| ## Security Overview | ||
|
|
||
| ### Permission | ||
|
|
||
| Each application is run in a sandbox to isolate security risks. When | ||
| interfacing between applications, if a one of those application is compromised | ||
| interfacing between applications, if a one of those applications is compromised |
There was a problem hiding this comment.
"if a one" -> "if one"
| complexity and a learning curve. Here is an introduction to the core concepts | ||
| embedded in Quark. | ||
|
|
||
| ## Inspiration |
There was a problem hiding this comment.
Do we really want to remove the inspiration section? I kind of like it! Maybe it could be formalized a bit... your call
There was a problem hiding this comment.
didn't know where to put it. how about at the end of the main README?
There was a problem hiding this comment.
i put it there, with slight modifications
|
Good catches @zramsay, please address my comments then I will merge (EF given permission) |
|
done |
|
dayum @nylira that cosmos-sdk logo looks so good here |
* Grammar fixes * Consensus state & height clarification * Rename validity predicate & misbehaviour predicate function signatures * Minor ICS 2 changes * Modify example slightly
…s#239) fix Update CHANGELOG.md Signed-off-by: yihuang <[email protected]> don't change interface
cosmos#239)" This reverts commit b693dd9.
cosmos#239)" (cosmos#247) This reverts commit b693dd9.
While prepping for #194 I did a bunch of cleaning up and eliminated reference to "quark". Parts of the
docs/quark/README.mdwere quite appropriate for the repo's readme and was edited & moved.