The Fuel RFC Book

RFCs for changes to Fuel or policies such as coding standards.

RFCs

Code Standards

Feature Name: N/A
Start Date: 2021-05-19
RFC PR: fuel-labs/rfcs#0004
Issue: N/A

Summary

The RFC establishes initial code standards for the FuelVM project. The code standards specify recommended default behaviors across the codebase. This will include best practices and stylistic preferences of the core team to ensure consistency and quality.

Motivation

Code standards are a useful tool to improve maintainability and accessibility of the code. They also provide the team a set of consistent standards that can be used to evaluate code submissions.

Guide-level explanation

Code standards live in the RFC repo, since they can be considered as an appendix to this RFC. These standards may be replicated to other locations for ease of access, but the version here will be considered the source of truth.

For future changes to the code standard, make a new RFC explaining the change along with the actual proposed changes to the code standards chapter of this mdbook.

Drawbacks

Debating code standards can lead to bikeshedding and distract developers from their tasks.

However, this may be offset by sticking to commonly established standards and by asserting that these are meant to be defaults that can be deviated from on a case-by-case basis if justified.

Rationale and alternatives

Using an RFC process to manage code style and standards has been done by the rust-lang team.

As far as specific standards, Rust has API design guidelines.

Unresolved questions

Code Standards

The following chapter defines the coding conventions and standards of the Fuel project. Updates to this code standard are to be accompanied by an RFC describing the rationale.

Rust Compiler Versions

RFC in progress here.

Building and Linting

CI should enforce the following criteria across all Rust projects:

Pull requests should be blocked if the build action fails.
The build action should deny all warnings.
Code formatting should pass cargo fmt --all -- --check
Code must pass cargo clippy

Clippy Lints

While clippy is a powerful tool, some lints may be incorrect or worse than the actual implementation. Each project should have its own clippy.toml file to maintain the set of lints are needed. Once the core sets of lints are configured for a project, #[allow(...)] exceptions should be placed nearest to the lint failure rather than globally at the clippy.toml file. An example of this may be when a Rust upgrade causes codegen from a macro to fail the updated lints.

Standard Lints

These lints are considered standard for every crate in the Fuel ecosystem.


#![allow(unused)]
#![warn(missing_docs)]
#![forbid(unsafe_code)]
fn main() {
}

Unused Dependencies

Each repo should have CI rules to prevent unused dependencies. This can be automated using the tool cargo-udeps.

Logging

Logging should be done using the tracing library to ensure consistent log output from all bins and libs.

Level	When to use
ERROR	Designates very serious errors.
WARN	Designates hazardous situations.
INFO	Designates useful information.
DEBUG	Designates lower priority information.
TRACE	Designates very low priority, often extremely verbose, information.

Security Auditing

All CI pipelines should use cargo audit to check for any known vulnerabilities in the dependency graph. If the audit fails, the build should fail until fixed.

If for some reason it's not feasible to avoid the audit error by patching dependencies, audit exceptions may be added to .cargo/audit.toml. When tagging a release, any exceptions in this file at the time should be noted and/or approved by the tech leads or security team.

SemVer

Versioning of crates should follow Rust standards.

https://doc.rust-lang.org/cargo/reference/semver.html

If the published artifact is a docker image or something other than a crate, it should attempt to follow similar rules to Rust API versioning when possible.

API Design

Refer to the Rust API Design guidelines. https://rust-lang.github.io/api-guidelines/

Code Review Standards for External Contributors

Code Line Limit: Pull requests should aim to not exceed 500 lines of additions. This helps to ensure that changes are small and easy to review, making it less likely for bugs to be introduced and easier to understand the changes. It also keeps the pull requests manageable in size and reduces the time needed for reviewing and approving.
Code Quality: Code should be clean, well-organized, and easy to read. It should follow the existing coding style and conventions used in the project. This makes the codebase consistent and easy to understand, which will help to maintain the project over time.
Comments: Code should be well-documented, providing explanations for the purpose, design, and reasoning of the code. Comments assist in clarifying the intent of the code, making it easier for others to work with and understand, even if they were not familiar with it previously. They also aid in making sure that others can comprehend the modifications made and how they fit into the overall project.
Test Coverage: All new code should be accompanied by unit tests that thoroughly exercise the new functionality. This helps to ensure that the code is working as intended and will continue to work correctly in the future.
Security: All code should be checked for potential security vulnerabilities. It is important to make security a top priority and regularly check and test code for any potential vulnerabilities.
Safety > Performance: Correctness of code must be guaranteed before unsafe code will be considered for review. Requests for the inclusion of unsafe code should be accompanied by benchmarks that demonstrate a measurable performance improvement, and/or code comments that clearly explain why the unsafe code is necessary before the code is considered for review.
PR Submission: When submitting a pull request, the contributor should provide a clear explanation of the changes made and their motivations behind the proposed modifications. It's recommended to include links to any related open issues in the PR description to make it easy for reviewers to understand the context and the problem that the code is trying to solve.
Sign Off: All pull requests from external contributors will need to be signed off by at least two internal contributors before they can be merged. This helps to ensure that changes are properly reviewed and that the quality of the codebase is maintained. It also allows for more experienced developers to mentor less experienced ones and help improve their contributions.
Compliance: All contributions must adhere to the project's open-source license and the contributor must agree to the terms of the license before submitting their code. This helps to ensure that the project stays in compliance with legal and ethical guidelines, and protects the rights of all parties involved.

By following these standards, external contributors can help to ensure that their code is of high-quality and easy to review. Adhering to these standards makes the project more reliable, sustainable, and maintainable in the long run, benefiting the project, community and the contributors.