docs: code guidelines changes (#20482)

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
-<some table>
-for tcIndex, tc := range cases {
-  <some code>
-  resp, err := doSomething()
-  require.NoError(err)
-  require.Equal(t, tc.expected, resp, "should correctly perform X")
-```
+    ```go
+        <some table>
+        for tcIndex, tc := range cases {
+        <some code>
+            resp, err := doSomething()
+            require.NoError(err)
+            require.Equal(t, tc.expected, resp, "should correctly perform X")
+    ```
 
 ## Quality Assurance
 

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. 
 
-<p align="center">
-  <img src="docs/semver.png?raw=true" alt="Releases Semver decision tree" width="40%" />
-</p>
+```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).
 
-<p align="center">
-  <img src="docs/0ver.png?raw=true" alt="Releases 0ver decision tree" width="40%" />
-</p>
+```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]
+```

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.