Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: code guidelines changes #20482

Merged
merged 4 commits into from
May 30, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 17 additions & 11 deletions CODING_GUIDELINES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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

Expand Down
22 changes: 16 additions & 6 deletions RELEASES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]
```
11 changes: 3 additions & 8 deletions RELEASE_PROCESS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.
Expand Down
Binary file removed docs/0ver.png
Binary file not shown.
Binary file removed docs/semver.png
Binary file not shown.
Loading