CONTRIBUTING.md

Contributing

Thank you for your interest in contributing! You can contribute by filing issues and submitting pull requests. Please observe our code of conduct.

If you submit a pull request, please ensure your change passes the GitHub Actions CI checks. This will be apparent from the required status check(s) in the pull request.

Rust style guide

We're fortunate to have good tooling around enforcing a consistent style throughout the codebase. If you have Toast, you can run the various lint checks by running toast lint. Otherwise, you can rely on our CI to do it for you. Here, we make note of a few conventions which are not yet enforced automatically. Please adhere to these conventions when possible, and provide appropriate justification for deviations from this guide. If you notice any style violations which appear unintentional, we invite you to bring them to our attention.

Comments

Rule: Comments should be written in American English.

Rule: Comments should always be capitalized unless they start with a code-like expression (see below).

Rule: Comments which are sentences should be punctuated appropriately. For example:

// The following logic implements beta reduction.

Rule: Comments which are not sentences should not have a trailing period. For example:

// Already normalized

Rule: Code-like expressions, such as variable names, should be surrounded by backticks. For example:

// `source_range` is a half-open interval, closed on the left and open on the right.

Trailing commas

The linter enforces that items in multi-line sequences (e.g., function arguments and macro arguments) have trailing commas.

Rule: Macros should be written to accept trailing commas as follows:

macro_rules! my_macro {
    ($foo:expr, $bar:expr, $baz:expr $(,)?) => {{
        ...
    }};
}

Guidelines for generated code

Generally speaking, we aim to have generated code follow the same standards as handwritten code, except when doing so would add significant complexity to the code generator. Below are some additional language-specific considerations.

Rust

Typical is designed to be invoked by a Cargo build script. See the example project for how to set that up. The user is expected to create a dedicated source file which locally disables lint checks for that file and then includes the generated code as follows:

#![allow(clippy::all, clippy::pedantic, clippy::nursery, warnings)]

include!(concat!(env!("OUT_DIR"), "/types.rs"));

Note that the Rust integration test disables specific checks rather than all of them to help us keep track of which checks we are violating.

TypeScript

To ensure it will pass formatting checks now and in the future, the generated code should disable Prettier for all top-level constructs as follows:

// prettier-ignore

To ensure it will pass lint checks now and in the future, the generated code should disable ESLint at the file level as follows:

// eslint-disable