docs: refactor contributing guidelines (cosmos#2706)

.github/PULL_REQUEST_TEMPLATE.md

@@ -43,7 +43,7 @@ write a little note why.
 
 - [ ] Targeted PR against correct branch (see [CONTRIBUTING.md](https://github.com/cosmos/ibc-go/blob/master/CONTRIBUTING.md#pr-targeting)).
 - [ ] Linked to Github issue with discussion and accepted design OR link to spec that describes this work.
-- [ ] Code follows the [module structure standards](https://github.com/cosmos/cosmos-sdk/blob/main/docs/docs/building-modules/10-structure.md).
+- [ ] Code follows the [module structure standards](https://github.com/cosmos/cosmos-sdk/blob/main/docs/docs/building-modules/10-structure.md) and [Go style guide](../docs/dev/go-style-guide.md).
 - [ ] Wrote unit and integration [tests](https://github.com/cosmos/ibc-go/blob/master/CONTRIBUTING.md#testing).
 - [ ] Updated relevant documentation (`docs/`) or specification (`x/<module>/spec/`).
 - [ ] Added relevant `godoc` [comments](https://blog.golang.org/godoc-documenting-go-code).

README.md

@@ -84,9 +84,23 @@ For questions and support please use the `developers` channel in the [Cosmos Net
 
 To receive announcements of new releases or other technical updates, please join the [Telegram group that we administer](https://t.me/ibc_is_expansive).
 
-## Contribution Guidelines & Requests for Maintainership
+## Contributing
 
-We have detailed documents for contributors wishing to [contribute code to ibc-go](https://github.com/cosmos/ibc-go/blob/main/CONTRIBUTING.md) or [submit a feature for maintainership](./MAINTAINERSHIP.md) in the `ibc-go` codebase. Please note that all maintainers of and contributors to the codebase are subject to the [Code of Conduct](https://github.com/cosmos/ibc-go/blob/main/CODE_OF_CONDUCT.md).
+If you're interested in contributing to ibc-go, please take a look at the [contributing guidelines](./CONTRIBUTING.md). We welcome and appreciate community contributions!
+
+This project adheres to ibc-go's [code of conduct](./CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
+
+To help contributors understand which issues are good to pick up, we have the following two categories:
+- Issues with the label [`good first issue`](https://github.com/cosmos/ibc-go/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) should be pretty well defined and are best suited for developers new to ibc-go.
+- Issues with the label [`help wanted`](https://github.com/cosmos/ibc-go/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) are a bit more involved and they usually require some familiarity already with the codebase.
+
+If you are interested in working on an issue, please comment on it; then we will be able to assign it to you. We will be happy to answer any questions you may have and help you out while you work on the issue.
+
+If you have any general questions or feedback, please reach out to us in the [IBC Gang Discord server](https://discord.com/channels/955868717269516318/955883113484013578).
+
+## Request for maintainership
+
+We have a document that describes the process for [submitting a feature for maintainership](./MAINTAINERSHIP.md) in the ibc-go codebase.
 
 ## Security
 

docs/DOCS_GUIDELINES.md

@@ -0,0 +1,40 @@
+# Documentation guidelines
+
+## Best practices
+
+- Check the spelling and grammar, even if you have to copy and paste from an external source.
+- Use simple sentences. Easy-to-read sentences mean the reader can quickly use the guidance you share.
+- Try to express your thoughts in a concise and clean way.
+- Either Leave a space or use a `-` between the acronyms ADR and ICS and the corresponding number (e.g. ADR 008 or ADR-008, and ICS 27 or ICS-27).
+- Don't overuse `code` format when writing in plain English.
+- Follow Google developer documentation [style guide](https://developers.google.com/style).
+- Check the meaning of words in Microsoft's [A-Z word list and term collections](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms) (use the search input!).
+- We recommend using RFC keywords in user documentation (lowercase). The RFC keywords are: "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).
+
+### Links
+
+**NOTE:** Strongly consider the existing links (both within this directory and to the website docs) when moving or deleting files.
+
+Relative links should be used nearly everywhere, due to versioning. Note that in case of page reshuffling, you must update all links references.
+
+### Code snippets
+
+Code snippets can be included in the documentation using normal Markdown code blocks. For example:
+
+```md
+    ```go
+    func() {}
+    ```
+```
+
+It is also possible to include code snippets from GitHub files by referencing the files directly (and the line numbers if needed). For example:
+
+```md
+    ```go reference
+    https://github.com/cosmos/ibc-go/blob/v5.0.0/modules/core/04-channel/keeper/handshake.go#L18-L65
+    ```
+```
+
+## Technical writing course
+
+Google provides a free [course](https://developers.google.com/tech-writing/overview) for technical writing.

docs/dev/development-setup.md

@@ -0,0 +1,60 @@
+# Development setup
+
+## Dependencies
+
+We use [Go 1.14 Modules](https://github.com/golang/go/wiki/Modules) to manage dependency versions.
+
+The main branch of every Cosmos repository should just build with `go get`, which means they should be kept up-to-date with their dependencies, so we can get away with telling  people they can just `go get` our software.
+
+Since some dependencies are not under our control, a third party may break our build, in which case we can fall back on `go mod tidy -v`.
+
+Other helpful commands:
+
+- `go get` to add a new go module (including if the existing go module is being semantic version bumped, i.e. my/module/v1 -> my/module/v2).
+- `go get -u` to update an existing dependency.
+- `go mod tidy` to update dependencies in `go.sum`.
+
+## Protobuf
+
+We use [Protocol Buffers](https://developers.google.com/protocol-buffers) along with [buf](https://docs.buf.build/introduction) and [gogoproto](https://github.com/gogo/protobuf) to generate code for use in ibc-go.
+
+For determinstic behavior around protobuf tooling, everything is containerized using Docker. Make sure to have Docker installed on your machine, or head to [Docker's website](https://docs.docker.com/get-docker/) to install it.
+
+For formatting code in `.proto` files, you can run the `make proto-format` command.
+
+For linting and checking breaking changes, we also use [buf](https://buf.build/). You can use the commands `make proto-lint` and `make proto-check-breaking` to respectively lint your proto files and check for breaking changes.
+
+To generate the protobuf stubs, you can run `make proto-gen`.
+
+We also added the `make proto-all` command to run the above commands (`proto-format`, `proto-lint` and `proto-gen`) sequentially.
+
+To update third-party protobuf dependencies, you can run `make proto-update-deps`. This requires `buf` to be installed in the local development environment (see [`buf`s installation documentation](https://docs.buf.build/installation) for more details).
+
+For generating or updating the swagger file that documents the URLs of the RESTful API that exposes the gRPC endpoints over HTTP, you can run the `proto-swagger-gen` command.
+
+It reads protobuf service definitions and generates a reverse-proxy server which translates a RESTful HTTP API into gRPC. 
+
+## Developing and testing
+
+- The latest state of development is on `main`.
+- Build the `simd` test chain binary with `make build`.
+- `main` must never fail `make test`.
+- No `--force` onto `main` (except when reverting a broken commit, which should seldom happen).
+- Create a development branch either on `github.com/cosmos/ibc-go`, or your fork (using `git remote add fork`).
+- Before submitting a pull request, begin `git rebase` on top of `main`.
+
+All Go tests in ibc-go can be ran by running `make test`.
+
+Please make sure to run `make format` before every commit - the easiest way to do this is have your editor run it for you upon saving a file. Additionally please ensure that your code is lint compliant by running `make lint-fix` (requires `golangci-lint`).
+
+When testing a function under a variety of different inputs, we prefer to use [table driven tests](https://github.com/golang/go/wiki/TableDrivenTests).
+
+All unit tests should use the testing package. Please see the testing package [README](../../testing/README.md) for more information.
+
+Test coverage is continuously deployed at https://app.codecov.io/github/cosmos/ibc-go. PRs that improve test coverage are welcome, but in general the test coverage should be used as a guidance for finding API use cases that are not covered by tests. We don't recommend adding tests that only improve coverage but not actually test a meaning use case.
+
+## Documentation
+
+- If you open a PR on ibc-go, it is mandatory to update the relevant documentation in `/docs`.
+- Generate the folder `docs/.vuepress/dist` with all the static files for the documentation site with `make build-docs`.
+- Run the documentation site locally with `make view-docs`.

docs/dev/go-style-guide.md

@@ -0,0 +1,115 @@
+
+# Go style guide
+
+In order to keep our code looking good with lots of programmers working on it, it helps to have a "style guide", so all the code generally looks quite similar. This doesn't mean there is only one "right way" to write code, or even that this standard is better than your style.  But if we agree to a number of stylistic practices, it makes it much easier to read and modify new code. Please feel free to make suggestions if there's something you would like to add or modify.
+
+We expect all contributors to be familiar with [Effective Go](https://golang.org/doc/effective_go.html) (and it's recommended reading for all Go programmers anyways). Additionally, we generally agree with the suggestions in [Uber's style guide](https://github.com/uber-go/guide/blob/master/style.md) and use that as a starting point.
+
+## Code Structure
+
+Perhaps more key for code readability than good commenting is having the right structure. As a rule of thumb, try to write in a logical order of importance, taking a little time to think how to order and divide the code such that someone could scroll down and understand the functionality of it just as well as you do. A loose example of such order would be:
+
+- Constants, global and package-level variables.
+- Main struct definition.
+- Options (only if they are seen as critical to the struct else they should be placed in another file).
+- Initialization/start and stop of the service functions.
+- Public functions (in order of most important).
+- Private/helper functions.
+- Auxiliary structs and function (can also be above private functions or in a separate file).
+
+## General
+
+- Use `gofumpt` to format all code upon saving it (or run `make format`).
+- Think about documentation, and try to leave godoc comments, when it will help new developers.
+- Every package should have a high level doc.go file to describe the purpose of that package, its main functions, and any other relevant information.
+- Applications (e.g. clis/servers) should panic on unexpected unrecoverable errors and print a stack trace.
+
+## Comments
+
+- Use a space after the comment deliminter (ex. `// your comment`).
+- Many comments are not sentences. These should begin with a lower case letter and end without a period.
+- Conversely, sentences in comments should be sentenced-cased and end with a period.
+- Comments should explain _why_ something is being done rather than _what_ the code is doing. For example:
+
+	The comments in 
+
+	```
+	// assign a variable foo
+	f := foo
+	// assign f to b
+	b := f
+	```
+
+	have little value,	but the following is more useful:
+
+	```
+	f := foo
+	// we copy the variable f because we want to preserve the state at time of initialization
+	b := f
+	```
+
+## Linting
+
+- Run `make lint-fix` to fix any linting errors.
+
+## Various
+
+- Functions that return functions should have the suffix `Fn`.
+- Names should not [stutter](https://blog.golang.org/package-names). For example, a struct generally shouldn’t have a field named after itself; e.g., this shouldn't occur:
+
+	``` golang
+	type middleware struct {
+		middleware Middleware
+	}
+	```
+
+- Acronyms are all capitalized, like "RPC", "gRPC", "API". "MyID", rather than "MyId".
+- Whenever it is safe to use Go's built-in `error` instantiation functions (as opposed to Cosmos SDK's error instantiation functions), prefer `errors.New()` instead of `fmt.Errorf()` unless you're actually using the format feature with arguments.
+
+## Importing libraries
+
+- Use [goimports](https://godoc.org/golang.org/x/tools/cmd/goimports).
+- Separate imports into blocks: one for the standard lib, one for external libs and one for application libs. For example:
+
+	```golang
+	import (
+		// standard library imports
+		"fmt"
+		"testing"
+					
+		// external library imports
+		"github.com/stretchr/testify/require"
+		abci "github.com/tendermint/tendermint/abci/types"
+					
+		// ibc-go library imports
+		"github.com/cosmos/ibc-go/modules/core/23-commitment/types"
+	)
+	```
+
+## Dependencies
+
+- Dependencies should be pinned by a release tag, or specific commit, to avoid breaking `go get` when external dependencies are updated.
+- Refer to the [contributing](./development-setup.md#dependencies) document for more details.
+
+## Testing
+
+- Make use of table driven testing where possible and not-cumbersome. Read [this blog post](https://dave.cheney.net/2013/06/09/writing-table-driven-tests-in-go) for more information. See the [tests](https://github.com/cosmos/ibc-go/blob/f24f41ea8a61fe87f6becab94e84de08c8aa9381/modules/apps/transfer/keeper/msg_server_test.go#L11) for [`Transfer`](https://github.com/cosmos/ibc-go/blob/f24f41ea8a61fe87f6becab94e84de08c8aa9381/modules/apps/transfer/keeper/msg_server.go#L15) for an example.
+- Make use of Testify [assert](https://godoc.org/github.com/stretchr/testify/assert) and [require](https://godoc.org/github.com/stretchr/testify/require).
+- When using mocks, it is recommended to use Testify [mock](https://pkg.go.dev/github.com/stretchr/testify/mock) along with [Mockery](https://github.com/vektra/mockery) for autogeneration.
+
+## Errors
+
+- Ensure that errors are concise, clear and traceable.
+- Depending on the context, use either `cosmossdk.io/errors` or `stdlib` error packages.
+- For wrapping errors, use `fmt.Errorf()` with `%w`.
+- Panic is appropriate when an internal invariant of a system is broken, while all other cases (in particular, incorrect or invalid usage) should return errors.
+- Error messages should be formatted as following:
+
+	```golang
+	sdkerrors.Wrapf(
+		<most specific error type possible>,
+		"<optional text description ended by colon and space>expected %s, got %s",
+		<value 1>,
+		<value 2>
+	)
+	```

docs/dev/project-structure.md

@@ -0,0 +1,46 @@
+# Project structure
+
+If you're not familiar with the overall module structure from the SDK modules, please check this [document](https://github.com/cosmos/cosmos-sdk/blob/main/docs/docs/building-modules/10-structure.md) as prerequisite reading.
+
+Every Interchain Standard (ICS) has been developed in its own package. The development team separated the IBC TAO (Transport, Authentication, Ordering) ICS specifications from the IBC application level specification. The following sections describe the architecture of the most relevant directories that comprise this repository.
+
+## `modules` 
+
+This folder contains implementations for the IBC TAO (`core`), IBC applications (`apps`) and light clients (`light-clients`). 
+
+### `core`
+
+- `02-client`: This package is an implementation for Cosmos SDK-based chains of [ICS 02](https://github.com/cosmos/ibc/tree/main/spec/core/ics-002-client-semantics). This implementation defines the types and methods needed to operate light clients tracking other chain's consensus state.
+- `03-connection`: This package is an implementation for Cosmos SDK-based chains of [ICS 03](https://github.com/cosmos/ibc/tree/main/spec/core/ics-003-connection-semantics). This implementation defines the types and methods necessary to perform connection handshake between two chains.
+- `04-channel`: This package is an implementation for Cosmos SDK-based chains of [ICS 04](https://github.com/cosmos/ibc/tree/main/spec/core/ics-004-channel-and-packet-semantics). This implementation defines the types and methods necessary to perform channel handshake between two chains and ensure correct packet sending flow.
+- `05-port`: This package is an implementation for Cosmos SDK-based chains of [ICS 05](https://github.com/cosmos/ibc/tree/main/spec/core/ics-005-port-allocation). This implements the port allocation system by which modules can bind to uniquely named ports.
+- `23-commitment`: This package is an implementation for Cosmos SDK-based chains of [ICS 23](https://github.com/cosmos/ibc/tree/main/spec/core/ics-023-vector-commitments). This implementation defines the functions required to prove inclusion or non-inclusion of particular values at particular paths in state.
+- `24-host`: This package is an implementation for Cosmos SDK-based chains of [ICS 24](https://github.com/cosmos/ibc/tree/main/spec/core/ics-024-host-requirements).
+
+### `apps`
+
+- `transfer`: This is the Cosmos SDK implementation of the [ICS 20](https://github.com/cosmos/ibc/tree/main/spec/app/ics-020-fungible-token-transfer) protocol, which enables cross-chain fungible token transfers. For more information, read the [module's docs](../apps/transfer/overview.md)
+- `27-interchain-accounts`: This is the Cosmos SDK implementation of the [ICS 27](https://github.com/cosmos/ibc/tree/main/spec/app/ics-027-interchain-accounts) protocol, which enables cross-chain account management built upon IBC. For more information, read the [module's documentation](../apps/interchain-accounts/overview.md).
+- `29-fee`: This is the Cosmos SDK implementation of the [ICS 29](https://github.com/cosmos/ibc/tree/main/spec/app/ics-029-fee-payment) middleware, which handles packet incentivisation and fee distribution on top of any ICS application protocol, enabling fee payment to relayer operators. For more information, read the [module's documentation](../middleware/ics29-fee/overview.md).
+
+### `light-clients`
+
+- `06-solomachine`: This package implement the types for the Solo Machine light client specified in [ICS 06](https://github.com/cosmos/ibc/tree/main/spec/client/ics-006-solo-machine-client).
+- `07-tendermint`: This package implement the types for the Tendermint consensus light client as specified in [ICS 07](https://github.com/cosmos/ibc/tree/main/spec/client/ics-007-tendermint-client).
+
+## `proto`
+
+This folder contains all the Protobuf files used for
+
+- common message type definitions,
+- message type definitions related to genesis state,
+- `Query` service and related message type definitions,
+- `Msg` service and related message type definitions.
+
+## `testing`
+
+This package contains the implementation of the testing package used in unit and integration tests. Please read the [package's documentation](../../testing/README.md) for more information.
+
+## `e2e`
+
+This folder contains all the e2e tests of ibc-go. Please read the [module's documentation](../../e2e/README.md) for more information.