Documentation Structure Change and Cleanup (#2808)
* Update docs/sdk/clients.md * organize ADR directory like tendermint * docs: move spec-proposals into spec/ * remove lotion, moved to website repo * move getting-started to cosmos-hub, and voyager to website * docs: move lite/ into clients/lite/ * move introduction/ content to website repo * move resources/ content to website repo * mv sdk/clients.md to clients/clients.md * mv validators to cosmos-hub/validators * move deprecated sdk/ content to _attic * sdk/modules.md is duplicate with modules/README.md * consolidate remianing sdk/ files into a single sdk.md * move examples/ to docs/examples/ * mv docs/cosmos-hub to docs/gaia * Add keys/accounts section to localnet docs
This commit is contained in:
gamarin2
Jack Zampolin
@@ -0,0 +1,94 @@
|
||||
# ADR 002: SDK Documentation Structure
|
||||
|
||||
## Context
|
||||
|
||||
There is a need for a scalable structure of the SDK documentation. Current documentation includes a lot of non-related SDK material, is difficult to maintain and hard to follow as a user.
|
||||
|
||||
Ideally, we would have:
|
||||
- All docs related to dev frameworks or tools live in their respective github repos (sdk repo would contain sdk docs, hub repo would contain hub docs, lotion repo would contain lotion docs, etc.)
|
||||
- All other docs (faqs, whitepaper, high-level material about Cosmos) would live on the website.
|
||||
|
||||
## Decision
|
||||
|
||||
Re-structure the `/docs` folder of the SDK github repo as follows:
|
||||
|
||||
```
|
||||
docs/
|
||||
├── README
|
||||
├── intro/
|
||||
├── gaia/
|
||||
│ ├── overview.md
|
||||
│ ├── install.md
|
||||
│ ├── join-testnet.md
|
||||
│ ├── validator-node.md
|
||||
│ ├── validator-faq.md
|
||||
│ └── delegator-faq.md
|
||||
├── reference/
|
||||
│ ├── baseapp
|
||||
│ ├── types
|
||||
│ ├── store
|
||||
│ ├── server
|
||||
│ ├── modules/
|
||||
│ │ ├── keeper
|
||||
│ │ ├── handler
|
||||
│ │ ├── cli
|
||||
│ ├── gas
|
||||
│ └── commands
|
||||
├── examples/
|
||||
│ ├── basecoin/
|
||||
│ └── democoin/
|
||||
├── clients/
|
||||
│ ├── lite/
|
||||
│ ├── service-providers
|
||||
├── spec/
|
||||
└── architecture/
|
||||
```
|
||||
|
||||
The files in each sub-folders do not matter and will likely change. What matters is the sectioning:
|
||||
|
||||
- `README`: Landing page of the docs.
|
||||
- `into`: Introductory material. Goal is to have a short explainer of the SDK and then channel people to the resource they need. The [sdk-tutorial](https://github.com/cosmos/sdk-application-tutorial/) will be highlighted, as well as the `godocs`.
|
||||
- `gaia`: Contains all docs related to the `gaia` application. Will later be renamed to `cosmos-hub` or `chub` and probably moved to its own repository.
|
||||
- `reference`: Contains high-level explanations of the abstractions of the SDK. It does not contain specific code implementation and does not need to be updated often. **It is not an API specification of the interfaces**. API spec is the `godoc`.
|
||||
- `examples`: Contain a couple examples of sdk application like `basecoin` and `democoin`. Developers need to maintain them up-to-date and make sure they compile as the SDK gets upgraded.
|
||||
- `clients`: Contains specs and info about the various SDK clients.
|
||||
- `spec`: Contains specs of modules, and others.
|
||||
- `architecture`: Contains architecture-related docs like the present one.
|
||||
|
||||
Website docs sidebar will only include the following sections:
|
||||
|
||||
- `README`
|
||||
- `intro`
|
||||
- `gaia`
|
||||
- `reference`
|
||||
- `clients`
|
||||
|
||||
`architecture` and `examples` need not be displayed on the website. As for `modules`, we might need to think about creating a modules manager, but this is out of scope for this document.
|
||||
|
||||
## Status
|
||||
|
||||
Proposed
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- Much clearer organisation of the SDK docs.
|
||||
- The `/docs` folder now only contains SDK and gaia related material. Later, it will only contain SDK related material.
|
||||
- Developers only have to update `/docs` folder when they open a PR (and not `/examples` for example).
|
||||
- Easier for developers to find what they need to update in the docs thanks to reworked architecture.
|
||||
- Cleaner vuepress build for website docs.
|
||||
- Will help build an executable doc (cf https://github.com/cosmos/cosmos-sdk/issues/2611)
|
||||
|
||||
### Neutral
|
||||
|
||||
- We need to move a bunch of deprecated stuff to `/_attic` folder.
|
||||
- We need to integrate content in `docs/sdk/docs/core` in `reference`.
|
||||
- We need to move all the content that currently lives in `docs` and does not fit in new structure (like `lotion`, intro material, whitepaper) to the website repository.
|
||||
- Update `DOCS_README.md`
|
||||
|
||||
## References
|
||||
|
||||
- https://github.com/cosmos/cosmos-sdk/issues/1460
|
||||
- https://github.com/cosmos/cosmos-sdk/pull/2695
|
||||
- https://github.com/cosmos/cosmos-sdk/issues/2611
|
||||
@@ -1,22 +0,0 @@
|
||||
# Architecture Decision Records (ADR)
|
||||
|
||||
This is a location to record all high-level architecture decisions in the cosmos-sdk project.
|
||||
|
||||
You can read more about the ADR concept in this [blog post](https://product.reverb.com/documenting-architecture-decisions-the-reverb-way-a3563bb24bd0#.78xhdix6t).
|
||||
|
||||
An ADR should provide:
|
||||
|
||||
- Context on the relevant goals and the current state
|
||||
- Proposed changes to achieve the goals
|
||||
- Summary of pros and cons
|
||||
- References
|
||||
- Changelog
|
||||
|
||||
Note the distinction between an ADR and a spec. The ADR provides the context, intuition, reasoning, and
|
||||
justification for a change in architecture, or for the architecture of something
|
||||
new. The spec is much more compressed and streamlined summary of everything as
|
||||
it stands today.
|
||||
|
||||
If recorded decisions turned out to be lacking, convene a discussion, record the new decisions here, and then modify the code to match.
|
||||
|
||||
Note the context/background should be written in the present tense.
|
||||
@@ -1,54 +0,0 @@
|
||||
# ADR 001: Global Message Counter
|
||||
|
||||
## Context
|
||||
|
||||
There is a desire for modules to have a concept of orderings between messages.
|
||||
|
||||
One such example is in staking, we currently use an "intra bond tx counter" and
|
||||
bond height.
|
||||
The purpose these two serve is to providing an ordering for validators with equal stake,
|
||||
for usage in the power-ranking of validators.
|
||||
We can't use address here, as that would create a bad incentive to grind
|
||||
addresses that optimized the sort function, which lowers the private key's
|
||||
security.
|
||||
Instead we order by whose transaction appeared first, as tracked by bondHeight
|
||||
and intra bond tx counter.
|
||||
|
||||
This logic however should not be unique to staking.
|
||||
It is very conceivable that many modules in the future will want to be able to
|
||||
know the ordering of messages / objects after they were initially created.
|
||||
|
||||
## Decision
|
||||
|
||||
Create a global message counter field of type int64.
|
||||
Note that with int64's, there is no fear of overflow under normal use,
|
||||
as it is only getting incremented by one,
|
||||
and thus has a space of 9 quintillion values to go through.
|
||||
|
||||
This counter must be persisted in state, but can just be read and written on
|
||||
begin/end block respectively.
|
||||
This field will get incremented upon every DeliverTx,
|
||||
regardless if the transaction succeeds or not.
|
||||
It must also be incremented within the check state for CheckTx.
|
||||
The global message ordering field should be set within the context
|
||||
so that modules can access it.
|
||||
|
||||
## Corollary - Intra block ordering
|
||||
In the event that there is desire to just have an intra block msg counter,
|
||||
this can easily be derived from the global message counter.
|
||||
Simply subtract current counter from first global message counter in the block.
|
||||
Thus the relevant module could easily implement this.
|
||||
|
||||
## Status
|
||||
Proposed
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
* Moves message ordering out of the set of things staking must keep track of
|
||||
* Abstracts the logic well so other modules can use it
|
||||
|
||||
### Negative
|
||||
* Another thing to implement prelaunch. (Though this should be easy to implement)
|
||||
|
||||
### Neutral
|
||||
@@ -1,32 +0,0 @@
|
||||
# ADR {ADR-NUMBER}: {TITLE}
|
||||
|
||||
## Changelog
|
||||
* {date}: {changelog}
|
||||
|
||||
## Context
|
||||
> This section contains all the context one needs to understand the current state, and why there is a problem. It should be as succinct as possible and introduce the high level idea behind the solution.
|
||||
|
||||
## Decision
|
||||
> This section explains all of the details of the proposed solution, including implementation details.
|
||||
It should also describe affects / corollary items that may need to be changed as a part of this.
|
||||
If the proposed change will be large, please also indicate a way to do the change to maximize ease of review.
|
||||
(e.g. the optimal split of things to do between separate PR's)
|
||||
|
||||
## Status
|
||||
> A decision may be "proposed" if it hasn't been agreed upon yet, or "accepted" once it is agreed upon. If a later ADR changes or reverses a decision, it may be marked as "deprecated" or "superseded" with a reference to its replacement.
|
||||
|
||||
{Deprecated|Proposed|Accepted}
|
||||
|
||||
## Consequences
|
||||
> This section describes the consequences, after applying the decision. All consequences should be summarized here, not just the "positive" ones.
|
||||
|
||||
### Positive
|
||||
|
||||
### Negative
|
||||
|
||||
### Neutral
|
||||
|
||||
## References
|
||||
> Are there any relevant PR comments, issues that led up to this, or articles referrenced for why we made the given design choice? If so link them here!
|
||||
|
||||
* {reference link}
|
||||
Reference in New Issue
Block a user