docs: improve README and CONTRIBUTING, add reference to testing guide (…

…#1199)

Co-authored-by: Manfred Touron <94029+moul@users.noreply.github.com>

CONTRIBUTING.md

@@ -1,7 +1,7 @@
-# Contributing to GNO
+# Contributing to Gno
 
-Thank you for looking to contribute to the GNO project.
-We appreciate every open-source contribution, as it helps us improve and enhance gno for the benefit of the community.
+Thank you for looking to contribute to the Gno project.
+We appreciate every open-source contribution, as it helps us improve and enhance Gno for the benefit of the community.
 
 This document outlines some basic pointers on making your future contribution a great experience. It outlines basic PR
 etiquette employed by the core gno team. It lays out coding styles, simple how-to guides and tools to get you up and
@@ -20,7 +20,7 @@ Likewise, if you have an idea on how to improve this guide, go for it as well.
     - [Testing](#testing)
       - [Running locally](#running-locally)
       - [Running test workflows](#running-test-workflows)
-      - [Testing GNO code](#testing-gno-code)
+      - [Testing Gno code](#testing-gno-code)
     - [Repository Structure](#repository-structure)
 - [How do I?](#how-do-i)
     - [How do I submit changes?](#how-do-i-submit-changes)
@@ -41,9 +41,9 @@ Likewise, if you have an idea on how to improve this guide, go for it as well.
 
 - **[Discord](https://discord.gg/YFtMjWwUN7)** - we are very active on Discord. Join today and start discussing all
   things gno with fellow engineers and enthusiasts.
-- **[Awesome GNO](https://github.com/gnolang/awesome-gno)** - check out the list of compiled resources for helping you
+- **[Awesome Gno](https://github.com/gnolang/awesome-gno)** - check out the list of compiled resources for helping you
   understand the gno ecosystem
-- **[Active Staging](https://gno.land/)** - use the currently available staging environment to play around with a
+- **[Active Staging](https://staging.gno.land/)** - use the currently available staging environment to play around with a
   production network. If you want to interact with a local instance, refer to the [Local Setup](#local-setup) guide.
 - **[Twitter](https://twitter.com/_gnoland)** - follow us on Twitter to get the latest scoop
 - **[Telegram](https://t.me/gnoland)** - join our official Telegram group to start a conversation about gno
@@ -58,7 +58,6 @@ The primary tech stack for working on the repository:
 
 - Go (version 1.20+)
 - make (for using Makefile configurations)
-- Docker (for using the official Docker setup files)
 
 It is recommended to work on a Unix environment, as most of the tooling is built around ready-made tools in Unix (WSL2
 for Windows / Linux / macOS).
@@ -70,8 +69,11 @@ with `make install_gno`.
 Additionally, you can also configure your editor to recognize `.gno` files as `.go` files, to get the benefit of syntax
 highlighting.
 
-Currently, we support a [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=harry-hov.gno) extension
-(eventually official in the future) for Gnolang.
+#### Visual Studio Code
+
+There currently is an unofficial [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=harry-hov.gno)
+extension (primarily developed by a core team member) for working with `*.gno`
+files.
 
 #### ViM Support
 
@@ -122,9 +124,36 @@ Clone the repo:
 `git clone https://github.com/gnolang/gno.git`
 
 Build / install base commands:
-`make build `
+`make install`
+
+If you haven't already, you may need to add the directory where [`go install`
+places its binaries](https://pkg.go.dev/cmd/go#hdr-Compile_and_install_packages_and_dependencies)
+to your `PATH`. If you haven't configured `GOBIN` or `GOPATH` differently, this
+command should suffice:
+
+```
+echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.profile
+source ~/.profile # reload ~/.profile in the current shell
+```
+
+After that, you should be good to go to use `gno` and `gnokey`, straight from
+your command line! The following commands should list the help messages for
+each:
 
-That’s it!
+```console
+$ gno --help
+USAGE
+  <subcommand> [flags] [<arg>...]
+
+Runs the gno development toolkit
+[...]
+$ gnokey --help
+USAGE
+  <subcommand> [flags] [<arg>...]
+
+Manages private keys for the node
+[...]
+```
 
 ### Testing
 
@@ -151,7 +180,7 @@ To run the entire test suite through workflow files, run the following command:
 
     act -v -j go-test
 
-#### Testing GNO code
+#### Testing Gno code
 
 If you wish to test a `.gno` Realm or Package, you can utilize the `gno` tool.
 
@@ -169,24 +198,35 @@ subcommands by running:
 
     gno --help
 
+#### Adding new tests
+
+Most packages will follow the convention established with Go: each package
+contains within its file many files suffixed with `_test.go` which test its
+functionality. As a general rule, you should follow this convention, and in
+every PR you make you should ensure all the code you added is appropriately
+covered by tests ([Codecov](https://about.codecov.io/) will loudly complain in
+your PR's comments if you don't).
+
+Additionally, we have a few testing systems that stray from this general rule;
+at the time of writing, these are for integration tests and language tests. You
+can find more documentation about them [on this guide](gno/docs/testing-guide.md).
+
 ### Repository Structure
 
 The repository structure can seem tricky at first, but it’s simple if you consider the philosophy that the gno project
-employs (check out [PHILOSOPHY.md](https://github.com/gnolang/gno/blob/master/PHILOSOPHY.md)).
+employs (check out [PHILOSOPHY.md](./PHILOSOPHY.md)).
 
 The gno project currently favors a mono-repo structure, as it’s easier to manage contributions and keep everyone
 aligned. In the future, this may change, but in the meantime the majority of gno resources and source code will be
 centralized here.
 
-- `cmd` - contains the base command implementations for tools like `gnokey`, `gnotxport`, etc. The actual underlying
-  logic is located within the `pkgs` subdirectories.
 - `examples` - contains the example `.gno` realms and packages. This is the central point for adding user-defined realms
   and packages.
-- `gnoland` - contains the base source code for bootstrapping the Gnoland node
-- `pkgs` - contains the dev-audited packages used throughout the gno codebase
-- `stdlibs` - contains the standard library packages used (imported) in `.gno` Smart Contracts. These packages are
-  themselves `.gno` files.
-- `tests` - contains the standard language tests for Gnolang
+- `gno.land` - contains the base source code for bootstrapping the Gnoland node,
+  using `tm2` and `gnovm`.
+- `gnovm` - contains the implementation of the Gno programming language and its
+  Virtual Machine, together with their standard libraries and tests.
+- `tm2` - contains a fork of the [Tendermint consensus engine](https://docs.tendermint.com/v0.34/introduction/what-is-tendermint.html) with different expectations.
 
 ## How do I?
 

README.md

@@ -1,35 +1,64 @@
 # Gno
 
-At first, there was Bitcoin, out of entropy soup of the greater All.
-Then, there was Ethereum, which was created in the likeness of Bitcoin,
-but made Turing complete.
+> At first, there was Bitcoin, out of entropy soup of the greater All.
+> Then, there was Ethereum, which was created in the likeness of Bitcoin,
+> but made Turing complete.
+>
+> Among these were Tendermint and Cosmos to engineer robust PoS and IBC.
+> Then came Gno upon Cosmos and there spring forth Gnoland,
+> simulated by the Gnomes of the Greater Resistance.
+
+Gno is an interpreted and fully-deterministic implementation of the Go
+programming language, designed to build succint and composable smart contracts.
+The first blockchain to use it is Gno.land, a
+[Proof of Contribution](./docs/proof-of-contribution.md)-based chain, backed by
+a variation of the [Tendermint](https://docs.tendermint.com/v0.34/introduction/what-is-tendermint.html)
+consensus engine.
 
-Among these were Tendermint and Cosmos to engineer robust PoS and IBC.
-Then came Gno upon Cosmos and there spring forth Gnoland,
-simulated by the Gnomes of the Greater Resistance.
+## Getting started
+
+If you haven't already, take a moment to check out our [website](https://gno.land/).
+
+> The website is a deployment of our [gnoweb](./gno.land/cmd/gnoweb) frontend; you
+> can use it to check out [some](https://test3.gno.land/r/demo/boards) [example](https://test3.gno.land/r/gnoland/blog)
+> [contracts](https://test3.gno.land/r/demo/users).
+>
+> Use the `[source]` button in the header to inspect the program's source; use
+> the `[help]` button to view how you can use [`gnokey`](./gno.land/cmd/gnokey)
+> to interact with the chain from your command line.
+
+If you have already played around with the website, use our
+[Getting Started](https://github.com/gnolang/getting-started) guide to learn how
+to write and deploy your first smart contract. No local set-up required!
+
+Once you're done, learn how to set up your local environment with the
+[quickstart guide](./examples/gno.land/r/demo/boards/README.md) and the
+[contributing guide](./CONTRIBUTING.md).
 
-## Discover
+You can find out more existing tools & documentation for Gno on our
+[awesome-gno](https://github.com/gnolang/awesome-gno) repository.
+We look forward to seeing your first PR!
+
+## Repository structure
 
 * [examples](./examples) - smart-contract examples and guides for new Gno developers.
 * [gnovm](./gnovm) - GnoVM and Gnolang.
 * [gno.land](./gno.land) - Gno.land blockchain and tools.
 * [tm2](./tm2) - Tendermint2.
 
-## Getting started
-
-Start your journey with Gno.land by:
-- using the [`gnoweb`](./gno.land/cmd/gnoweb) interface on the [latest testnet (test3.gno.land)](https://test3.gno.land/),
-- sending transactions with [`gnokey`](./gno.land/cmd/gnokey),
-- writing smart-contracts with [`gno` (ex `gnodev`)](./gnovm/cmd/gno).
-
-Also, see the [quickstart guide](https://github.com/gnolang/gno/blob/master/examples/gno.land/r/demo/boards/README.md).
+## Socials & Contact
 
-## Contact
-
- * Discord: https://discord.gg/YFtMjWwUN7 <-- join now
- * Gnoland: https://gno.land/r/demo/boards:testboard
- * Telegram: https://t.me/gnoland
- * Twitter: https://twitter.com/_gnoland
+* [**Discord**](https://discord.gg/YFtMjWwUN7): good for general chat-based
+  conversations, as well as for asking support on developing with Gno.
+* [**Reddit**](https://www.reddit.com/r/gnoland): more "permanent" and
+  forum-style discussions. Feel free to post anything Gno-related, as well as
+  any question related to Gno programming!
+* [**Telegram**](https://t.me/gnoland): unofficial Telegram group.
+* [**Twitter**](https://twitter.com/_gnoland): official Twitter account. Follow
+   us to know about new developments, events & official announcements about Gno!
+* [**YouTube**](https://www.youtube.com/@_gnoland): here we post all of our
+  video content, like workshops, talks and public development calls. Follow
+  along on our development journey!
 
 <details><summary>Short doc about all the commands</summary>
 
@@ -52,28 +81,28 @@ Also, see the [quickstart guide](https://github.com/gnolang/gno/blob/master/exam
 <details><summary>CI/CD/Tools badges and links</summary>
 
   GitHub Actions:
-  
+
   * [![gno.land](https://github.com/gnolang/gno/actions/workflows/gnoland.yml/badge.svg)](https://github.com/gnolang/gno/actions/workflows/gnoland.yml)
   * [![gnovm](https://github.com/gnolang/gno/actions/workflows/gnovm.yml/badge.svg)](https://github.com/gnolang/gno/actions/workflows/gnovm.yml)
   * [![tm2](https://github.com/gnolang/gno/actions/workflows/tm2.yml/badge.svg)](https://github.com/gnolang/gno/actions/workflows/tm2.yml)
   * [![examples](https://github.com/gnolang/gno/actions/workflows/examples.yml/badge.svg)](https://github.com/gnolang/gno/actions/workflows/examples.yml)
   * [![docker](https://github.com/gnolang/gno/actions/workflows/docker.yml/badge.svg)](https://github.com/gnolang/gno/actions/workflows/docker.yml)
-  
+
   Codecov:
-  
+
   * General: [![codecov](https://codecov.io/gh/gnolang/gno/branch/master/graph/badge.svg?token=HPP82HR1P4)](https://codecov.io/gh/gnolang/gno)
   * tm2: [![codecov](https://codecov.io/gh/gnolang/gno/branch/master/graph/badge.svg?token=HPP82HR1P4&flag=tm2)](https://codecov.io/gh/gnolang/gno/tree/master/tm2)
   * gnovm: [![codecov](https://codecov.io/gh/gnolang/gno/branch/master/graph/badge.svg?token=HPP82HR1P4&flag=gnovm)](https://codecov.io/gh/gnolang/gno/tree/master/gnovm)
   * gno.land: [![codecov](https://codecov.io/gh/gnolang/gno/branch/master/graph/badge.svg?token=HPP82HR1P4&flag=gno.land)](https://codecov.io/gh/gnolang/gno/tree/master/gno.land)
   * examples: TODO
-  
+
   Go Report Card:
-  
+
   * [![Go Report Card](https://goreportcard.com/badge/github.com/gnolang/gno)](https://goreportcard.com/report/github.com/gnolang/gno)
   * tm2, gnovm, gno.land: TODO (blocked by tm2 split, because we need go mod workspaces)
-  
+
   Pkg.go.dev
-  
+
   * [![Go Reference](https://pkg.go.dev/badge/github.com/gnolang/gno.svg)](https://pkg.go.dev/github.com/gnolang/gno)
   * TODO: host custom docs on gh-pages, to bypass license limitation
 </details>