From 0b15cfa77d5a05b8820790ee74a3628b17c7b014 Mon Sep 17 00:00:00 2001 From: kogisin Date: Fri, 10 Sep 2021 12:03:22 +0900 Subject: [PATCH 01/12] docs: update README.md --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 5220299..117b4a5 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # Budget Module -A budget module is a Cosmos SDK module that implements budget functionality. +A budget module is a Cosmos SDK module that implements budget functionality. It is an independent module from other SDK modules and core functionality is to distribute inflation and gas fees to different budget plans. Read [spec docs](./x/budget/spec/01_concepts.md) to get to know more about the module. -⚠ **Budger module v1 is in active development - see "master" branch for the v1 mainnet version** ⚠ +⚠ **Budger module v1 is in active development - see "master" branch for the latest update** ⚠ ## Installation ### Requirements @@ -14,7 +14,7 @@ Requirement | Notes Go version | Go1.15 or higher Cosmos SDK | v0.44.0 or higher -### Get Farming Module source code +### Get Budget Module source code ```bash git clone https://github.com/tendermint/budget.git From af8faab035e45666c35cbf4e31ab6e4922a61b9e Mon Sep 17 00:00:00 2001 From: kogisin Date: Fri, 10 Sep 2021 12:18:03 +0900 Subject: [PATCH 02/12] docs: add docs folder and apply folder structure with ADR guides --- docs/Explanation/ADR/PROCESS.md | 67 +++++ docs/Explanation/ADR/README.md | 39 +++ .../Explanation/ADR/adr-002-docs-structure.md | 270 ++++++++++++++++++ docs/Explanation/ADR/adr-template.md | 60 ++++ docs/Explanation/README.md | 66 +++++ docs/README.md | 36 +++ 6 files changed, 538 insertions(+) create mode 100644 docs/Explanation/ADR/PROCESS.md create mode 100644 docs/Explanation/ADR/README.md create mode 100644 docs/Explanation/ADR/adr-002-docs-structure.md create mode 100644 docs/Explanation/ADR/adr-template.md create mode 100644 docs/Explanation/README.md create mode 100644 docs/README.md diff --git a/docs/Explanation/ADR/PROCESS.md b/docs/Explanation/ADR/PROCESS.md new file mode 100644 index 0000000..0735802 --- /dev/null +++ b/docs/Explanation/ADR/PROCESS.md @@ -0,0 +1,67 @@ +# ADR Creation Process + +1. Copy the `adr-template.md` file. Use the following filename pattern: `adr-next_number-title.md` + +2. Create a draft Pull Request if you want to get an early feedback. + +3. Make sure the context and a solution is clear and well documented. + +4. Add an entry to a list in the [README](./README.md) file. + +5. Create a Pull Request to propose a new ADR. + +## ADR life cycle + +ADR creation is an **iterative** process. Instead of trying to solve all decisions in a single ADR pull request, we MUST initially understand the problem and collect feedback by having conversations in a GitHub Issue. + +1. Every ADR proposal SHOULD start with a [new GitHub issue](https://github.com/tendermint/starport/issues/new/choose) or be a result of existing Issues. The Issue must contain a brief proposal summary. + +2. After the motivation is validated, create a new document that is on the `adr-template.md`. + +3. An ADR solution doesn't have to arrive to the `master` branch with an _accepted_ status in a single PR. If the motivation is clear and the solution is sound, we SHOULD be able to merge PRs iteratively and keep a _proposed_ status. It's preferable to have an iterative approach rather than long, not merged Pull Requests. + +4. If a _proposed_ ADR is merged, then the outstanding changes must be clearly documented in outstanding issues in ADR document notes or in a GitHub Issue. + +5. The PR SHOULD always be merged. In the case of a faulty ADR, we still prefer to merge it with a _rejected_ status. The only time the ADR SHOULD NOT be merged is if the author abandons it. + +6. Merged ADRs SHOULD NOT be pruned. + +### ADR status + +Status has two components: + +``` +{CONSENSUS STATUS} {IMPLEMENTATION STATUS} +``` + +IMPLEMENTATION STATUS is either `Implemented` or `Not Implemented`. + +#### Consensus Status + +``` +DRAFT -> PROPOSED -> LAST CALL yyyy-mm-dd -> ACCEPTED | REJECTED -> SUPERSEEDED by ADR-xxx + \ | + \ | + v v + ABANDONED +``` + ++ `DRAFT`: [optional] an ADR which is work in progress, not being ready for a general review. This is to present an early work and get an early feedback in a Draft Pull Request form. + ++ `PROPOSED`: an ADR covering a full solution architecture and still in the review - project stakeholders haven't reached an agreed yet. + ++ `LAST CALL `: [optional] clear notify that we are close to accept updates. Changing a status to `LAST CALL` means that social consensus (of Budge module maintainers) has been reached and we still want to give it a time to let the community react or analyze. + ++ `ACCEPTED`: ADR which will represent a currently implemented or to be implemented architecture design. + ++ `REJECTED`: ADR can go from PROPOSED or ACCEPTED to rejected if the consensus among project stakeholders will decide so. + ++ `SUPERSEEDED by ADR-xxx`: ADR which has been superseded by a new ADR. + ++ `ABANDONED`: the ADR is no longer pursued by the original authors. + +## Language used in ADR + ++ Write the context/background in the present tense. + ++ Avoid using a first, personal form. \ No newline at end of file diff --git a/docs/Explanation/ADR/README.md b/docs/Explanation/ADR/README.md new file mode 100644 index 0000000..ac9496c --- /dev/null +++ b/docs/Explanation/ADR/README.md @@ -0,0 +1,39 @@ +# Architecture Decision Records (ADR) + +Use this location to record all high-level architecture decisions in the Budget module. + +### Definitions + +Within the context of an ADR we define the following: +An Architectural Decision (**AD**) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant. +An Architecturally Significant Requirement (**ASR**) is a requirement that has a measurable effect on a software system’s architecture and quality. +An Architectural Decision Record (**ADR**) captures a single AD, and is as often done when writing personal notes or meeting minutes. The collection of ADRs created and maintained in a project constitute its decision log. All these records are within the topic of Architectural Knowledge Management (AKM). + +You can read more about the ADR concept in the [Documenting architecture decisions, the Reverb way](https://product.reverb.com/documenting-architecture-decisions-the-reverb-way-a3563bb24bd0#.78xhdix6t) blog post. + +## Rationale + +ADRs are intended to be the primary mechanism for proposing new feature designs and new processes, for collecting community input on an issue, and for documenting the design decisions. +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 specification. The ADR provides the context, intuition, reasoning, and justification for a change in architecture, or for the architecture of something new. The specification is a summary of everything as it stands today. + +If recorded decisions turned out to be lacking the required substance, the process is to convene a discussion, record the new decisions here, and then modify the code to match. + +## Creating new ADR + +Read about the [PROCESS](./PROCESS.md). + +#### Use RFC 2119 Keywords + +When writing ADRs, follow the same best practices for writing RFCs. When writing RFCs, key words are used to signify the requirements in the specification. These words are often capitalized: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). + +## ADR Table of Contents + +- [ADR XXX: Self Sovereign Identity](./adr-001-self-sovereign-identity.md) \ No newline at end of file diff --git a/docs/Explanation/ADR/adr-002-docs-structure.md b/docs/Explanation/ADR/adr-002-docs-structure.md new file mode 100644 index 0000000..6e39e8e --- /dev/null +++ b/docs/Explanation/ADR/adr-002-docs-structure.md @@ -0,0 +1,270 @@ +# ADR 002: Documentation Structure + +## Status + +ACCEPTED + +## Abstract + +This ADR proposes a documentation strategy based on the *Grand Unified Theory of Documentation* (David Laing) as described by [Divio](https://documentation.divio.com/). + +The documentation strategy outlines four specific use cases for documentation. Based on these use cases and other non-functional requirements, a structure is proposed that will address these concerns using GitHub as the Content Management System. + +The documentation strategy also proposes: + +- The use and re-use of document and format templates +- Specific [code owners](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-code-owners#about-code-owners) for documentation +- Comment and commit templates combined with [githook](https://git-scm.com/docs/githooks) checks + +The outcome shall be focused, consistent, high quality documentation. + +## Context + +Good documentation is important to the success of software projects. + +*Writing excellent code doesn't end when your code compiles or even if your test coverage reaches 100%. It's easy to write something a computer understands, it's much harder to write something both a human and a computer understand. Your mission as a Code Health-conscious engineer is to write for humans first, computers second. Documentation is an important part of this skill.* [Google Documentation Best Practice](https://google.github.io/styleguide/docguide/best_practices.html) + +The documentation use cases, as outlined by Divio are: + +- Allow a new user to get started +- Show a user how to solve a specific problem +- Describe the machinery, for example, classes, functions, interfaces, parameters, and so on +- Explanation and context for design, scope, and so on + +![Documentation Quadrants](https://documentation.divio.com/_images/overview.png) + +The goals of well-structured and well-written documentation include: + +- Findability: depending on the use case, the technical content can be discovered and accessed +- Style: The documentation is written in an appropriate style for the use case +- Consistency: Each type of documentation is written in a consistent style +- Scoped: Documentation is scoped to a specific use case; for example, a tutorial can provide links but does not include technical content that describes why the software works, a tutorial just teaches how to use it + +Additional Documentation non-functional use cases include: + +- Technical content SHOULD BE as close to the code as reasonably practicable and strive to use the docs as code workflow +- Technical content SHOULD BE generated from code as much as possible +- Technical content SHOULD USE a consistent format +- Technical content SHOULD BE useable from within the repository +- Technical content COULD HAVE an automatic process that converts the content to a website based on [Read The Docs](https://readthedocs.com/), [Gitbook](https://www.gitbook.com/), or other suitable hosting systems + +## Decision + +To address the use cases outlined in the context, this ADR proposes the following decisions: + +- Use GitHub as primary content management [https://github.com/tendermint/budget](https://github.com/tendermint/budget) +- Use Markdown and LaTeX to deliver research publications + +Given GitHub will form the content management system, we propose the following structure: + +### Structure + +The documentation structure shall use as much as possible a content structure similar to the [Divio user cases](https://documentation.divio.com/introduction/). + +| | Tutorials | How-to guides | Reference | Explanation | +|-----------------|-----------|---------------|-------------|-------------- | +| **Oriented to** | Learning | A goal | Information | Understanding | +| **Must** | Allow a newcomer to get started | Show how to solve a specific problem | Describe the machinery | Explain | +| **Takes the form of** | A lesson | A series of steps | A dry description | A discursive explanation | +| **Analogy** | Teaching a child to cook | Recipe in a cookery book | An encyclopedia article | A paper on culinary social history | + +The specific implementation for Budget module SHOULD BE as per the following tree structure. + +``` +/ +├── README +├── CONTRIBUTING +├── TECHNICAL-SETUP +├── CODEOWNERS +├── x/ +| ├── module_a/ +| ├── README +| ├── docs/ +| ├── state +| ├── state_transitions +| ├── messages +├── docs/ + ├── README + ├── CODEOWNERS + ├── Explanation/ + | ├── README + | ├── ADR/ + | | ├── README + | | ├── PROCESS + | | ├── adr-template + | | ├── adr-{number}-{desc} + | ├── articles/ + | | ├── regulation-litepaper/ + | | ├── ARTICLE + | ├── research/ + | ├── README + | ├── research_topic/ + ├── How-To/ + | ├── HowToDoSomething/ + | ├── HowToDoSomethingElse/ + ├── Reference/ + | ├── README + | ├── GLOSSARY + | ├── MODULES + | ├── use-cases/ + | | ├── use-case-A + | | ├── use-case-B + | ├── architecture/ + ├── Tutorials/ + ├── Tutorial_1/ + ├── Tutorial_2/ +``` + +#### Root level documents + +The following files are required at the repo root level: + +- **README.md** - General repo overview to introduce the product and orientate the user. All README files must follow the best practices as outlined in the [GitHub README](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-readmes) guidelines. +- **TECHNICAL-SETUP.md** - Specific steps on getting started with the repo, can be a link to a tutorial or include the specific action-oriented steps + - Links to specific tooling setup requirements for development tools, linters, and so on + - Dependencies such as [pre-commit](https://pre-commit.com/) package manager + - Building the code + - Running tests +- **CONTRIBUTING.md** - Details on how new users can contribute to the project. In specific: + - Committing changes + - Commit message formats (see [Commit Comments](#commit-comments) + - Raising PRs + - Code of Conduct +- **CODEOWNERS** - Although not part of the documentation itself, a [CODEOWNERS file](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-code-owners) defines the code maintainers who are responsible for code in a repository and perform quality assurance on comments, PRs, and issues. + +#### Modules + +In line with Cosmos SDK convention (TODO: needs reference) each module contains its own relevant documentation: + +- **Module specifications** - A document that outlines state transitions `x/module-name/docs/` +- **Module-level README.md** e.g. x/module-name/README.md + +README files are classed as reference documentation. Content in module-level README files is descriptive, but explanatory. Explanations should be part of issues, Pull Requests, and docs/explanation/architecture. + +#### docs/ + +The `docs` folder shall include the following files and folders: + +- **README.md** - SHALL USE this for introduction and orientating the user, based on the content of this ADR and other materials. +- **CODEOWNERS** - This [CODEOWNERS file](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-code-owners) details the reviewers for documentation folder. The listed code owners SHALL INCLUDE the code maintainers in the root CODEOWNERS file plus a member of the Tendermint Technical Writing Team. + +#### docs/Reference + +Reference documentation includes a number of different forms: + +- **README.md** - This document outlines the purpose of the reference documentation as per the use-case documentation strategy and methodology. In addition, the README also links to documentation that is created from the code itself, specifically: + - Code Documentation in form of Go Docs + - Swagger API documentation +- **GLOSSARY.md** - Review and maintenance must be regularly and consistently applied. These form the terms of reference for users and ensure that discussion and design are based on consistent terms of reference. This file will be similar to [Cosmos Network Glossary](https://v1.cosmos.network/glossary) and can reference this. +- **MODULES.md** - A markdown document that has references to module-relevant documentation + +##### docs/Reference/use-cases + +The `use-cases` folder describes the Budget module use cases. Ideally, use cases are written in behavior-driven development (BDD) format. Use case content should be dry in nature and avoid explanations that should be covered in the explanation documentation. + +##### docs/Reference/architecture + +The `architecture` folder contains architecture diagrams such as component, activity, and sequence diagrams as relevant. Specifically, these assets should be in a format suitable for version management and easy to update. Therefore, these diagrams should be in SVG or DOT format and not image formats (JPEG, PNG, and so on). + +#### docs/Explanation + +The `Explanation` folder contains content that provides context for readers and is discursive in nature. See the [Divio Explanation page](https://documentation.divio.com/explanation/#) for more detail. + +- **docs/explanation/README.md** - This file orients the reader and explains the content. + +##### docs/Explanation/ADR + +The `ADR` folder tracks decisions regarding design and architecture (such as this documentation strategy). ADR content includes the following: + +- **docs/explanation/adr/README** - introduction to ADR +- **docs/explanation/adr/PROCESS.md** - describes how to raise ADRs +- **docs/explanation/adr/adr-template.md** - template for raising ADR +- **docs/explanation/adr/adr-{number}-{desc}.md** - an ADR document + +##### docs/Explanation/articles + +The `articles` folder contains a sub-folder for each published article. Published articles this COULD REFER to blog posts. The folder should be named such that it describes the article's purpose. Each sub-folder SHALL CONTAIN all the content relevant to the article (for example, images, bibliographies, and so on). These articles can be converted into PDF format using Pandoc. + +To convert articles to PDF using Pandoc: + +- There SHOULD BE a makefile with targets for calling Pandoc. Note: the process for building PDF files is not part of the commit or release processes, but ad-hoc +- There SHOULD BE a LaTeX template file that can create PDF files that have a consistent look and feel. This COULD BE the [Eisvogel template](https://github.com/Wandmalfarbe/pandoc-latex-template) with suitable modifications. +- The makefile and template should be independent of the article +- There SHOULD BE a README.md that describes how to use the makefile and template and build articles + +> **Note:** Explanations can come in other forms, particularly issue discussion and Pull Requests. + +#### docs/Tutorials + +As indicated in the overview, tutorials SHALL BE documents that target beginners and guide a user step-by-step through a process with the aim of achieving some goal. Please see the [Divio tutorial page](https://documentation.divio.com/tutorials/) for details. + +- There SHALL BE a folder for each tutorial. See the [Cosmos SDK tutorials](https://github.com/cosmos/sdk-tutorials) as an example. +- The folder SHALL CONTAIN all of the content that is relevant for that tutorial. +- The content SHOULD BE consistent in format with [Cosmos SDK tutorials](https://tutorials.cosmos.network/). + +#### docs/How-To + +In contrast to tutorials, [how-to guides](https://documentation.divio.com/how-to-guides/) are a series of actionable steps to help an experienced reader solve a specific problem. These how-to guides SHALL USE templates similar to the tutorials - see above. + +### Templates + +The documentation SHOULD USE Markdown templates to develop structured technical content, like module messages follow templates in the Cosmos SDK. + +- [The good docs project](https://github.com/thegooddocsproject) +- [Readme editor](https://readme.so/editor) + + +#### Code Comments + +PR review comments also form part of the documentation. Comments SHALL FOLLOW recommendation as per [Conventional Comments](https://conventionalcomments.org/) + +``` +