diff --git a/CODING_GUIDELINES.md b/CODING_GUIDELINES.md index 9208043573..60aeb11927 100644 --- a/CODING_GUIDELINES.md +++ b/CODING_GUIDELINES.md @@ -7,7 +7,7 @@ This document is an extension to [CONTRIBUTING](./CONTRIBUTING.md) and provides * Code must be well structured: * packages must have a limited responsibility (different concerns can go to different packages), * types must be easy to compose, - * think about maintainbility and testability. + * think about maintainability and testability. * "Depend upon abstractions, [not] concretions". * Try to limit the number of methods you are exposing. It's easier to expose something later than to hide it. * Take advantage of `internal` package concept. @@ -18,11 +18,11 @@ This document is an extension to [CONTRIBUTING](./CONTRIBUTING.md) and provides * Minimize code duplication. * Limit third-party dependencies. -Performance: +### Performance * Avoid unnecessary operations or memory allocations. -Security: +### Security * Pay proper attention to exploits involving: * gas usage @@ -31,6 +31,12 @@ Security: * code must be always deterministic * Thread safety. If some functionality is not thread-safe, or uses something that is not thread-safe, then clearly indicate the risk on each level. +### Documentation + +When writing code that is complex or relies on another piece of the code, it is advised to create a diagram or a flowchart to explain the logic. This will help other developers to understand the code and will also help you to understand the logic better. + +The Cosmos SDK uses [Mermaid.js](https://mermaid.js.org/), you can find the documentation on how to use it [here](https://mermaid.js.org/intro/). + ## Acceptance tests Start the design by defining Acceptance Tests. The purpose of Acceptance Testing is to @@ -108,14 +114,14 @@ The idea is you should be able to see the error message and figure out exactly what failed. Here is an example check: -```go - -for tcIndex, tc := range cases { - - resp, err := doSomething() - require.NoError(err) - require.Equal(t, tc.expected, resp, "should correctly perform X") -``` + ```go + + for tcIndex, tc := range cases { + + resp, err := doSomething() + require.NoError(err) + require.Equal(t, tc.expected, resp, "should correctly perform X") + ``` ## Quality Assurance diff --git a/RELEASES.md b/RELEASES.md index fd0fc3c267..ed4a74fa30 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -6,14 +6,24 @@ The Cosmos-SDK follows both [0ver](https://0ver.org/) and [Semver](https://semve Although we adhere to semantic versioning (semver), we have introduced a few modifications to accommodate the unique characteristics of blockchains. One significant divergence is that the major version (Y.x.x) is incremented solely when a consensus-breaking change occurs. On the other hand, the minor version (x.Y.x) is increased when there is a non-consensus-breaking alteration that also results in an incompatible API change. Patch versions will be bumped for all other changes that dont break the API nor Consensus. -

- Releases Semver decision tree -

+```mermaid +flowchart TD + A[Change] --> B{Consensus Breaking?} + B -->|Yes| C[Increase Major Version] + B -->|No| D{API Breaking?} + D -->|Yes| E[Increase Minor Version] + D -->|No| F[Increase Patch Version] +``` ## 0ver Dependencies In terms of the Cosmos-SDK dependency, we adhere to a simpler versioning approach known as 0ver. This flow differs from the previous Semver flow. Under this system, when a consensus-breaking change or an API-breaking change occurs, the Cosmos-SDK team increments the minor version (x.Y.x). Conversely, when a non-consensus-breaking change and a non-API-breaking change take place, the team bumps the patch version (x.x.Y). -

- Releases 0ver decision tree -

+```mermaid +flowchart TD + A[Change] --> B{Consensus Breaking?} + B -->|Yes| C[Increase Minor Version] + B -->|No| D{API Breaking?} + D -->|Yes| E[Increase Minor Version] + D -->|No| F[Increase Patch Version] +``` diff --git a/RELEASE_PROCESS.md b/RELEASE_PROCESS.md index 5af7b2a22f..37242e8750 100644 --- a/RELEASE_PROCESS.md +++ b/RELEASE_PROCESS.md @@ -46,12 +46,7 @@ v1.0.0-beta1 → v1.0.0-beta2 → ... → v1.0.0-rc1 → v1.0.0-rc2 → ... → * create a new annotated git tag (eg `git -a v1.1.0`) in the release branch. * Create a GitHub release. -Following _semver_ philosophy, point releases after `v1.0`: - -* must not break API -* can break consensus - -Before `v1.0`, point release can break both point API and consensus. +See the [Releases document](./RELEASES.md) for more information on the versioning scheme. ## Patch Release Procedure @@ -82,8 +77,8 @@ Major Release series is maintained in compliance with the **Stable Release Polic Only the following major release series have a stable release status: -* **0.47** is the previous major release and is supported until the release of **0.51.0**. A fairly strict **bugfix-only** rule applies to pull requests that are requested to be included into a not latest stable point-release. -* **0.50** is the last major release and is supported until the release of **0.52.0**. +* **0.47** is the previous major release and is supported until the release of **0.52.0**. A fairly strict **bugfix-only** rule applies to pull requests that are requested to be included into a not latest stable point-release. +* **0.50** is the last major release and is supported until the release of **0.54.0**. The SDK team maintains the last two major releases, any other major release is considered to have reached end of life. The SDK team will not backport any bug fixes to releases that are not supported. diff --git a/docs/0ver.png b/docs/0ver.png deleted file mode 100644 index 35f7a1fe6e..0000000000 Binary files a/docs/0ver.png and /dev/null differ diff --git a/docs/semver.png b/docs/semver.png deleted file mode 100644 index 49be36b926..0000000000 Binary files a/docs/semver.png and /dev/null differ