Known Problems

What are known problems

Known problems are what we call the currently discovered soundness issues in the Rust compiler. We need to list and describe these in a manner that we can show them to customers to make them aware of these issues.

The database and tooling for these live in

Classifying and describing a problem

When describing a new issue, the first step is to check if the issue applies to one of our supported targets. If that is not the case, we can discard it as it won’t be relevant to our customers.

If it does apply, copy the into the src folder, rename it to KP-R<ISSUE-NUMBER>.md and fill out the sections appropriately.

frontmatter title

The title summarizes the gist of the issue in a single phrase in terms of what went wrong. It’s easiest to look at another issue of the same category for inspiration.

frontmatter references

The references frontmatter links to the corresponding rust-lang/rust issue on github.

frontmatter tag

The tag frontmatter describes the category this issue belongs to. You can see the current categories here

frontmatter introduced-commit

The introduced-commit frontmatter lists the hash of the commit that introduced the issue. The hash is used to figure out from what Ferrocene version the issue applies. If it is not known since when the issue exists, leave it blank.

frontmatter fixed-commit

The fixed-commit frontmatter lists the hash of the commit that fixed the issue if it has already been fixed. Leave it blank if the issue is still open.

heading Description

The Description section gives a general description of the issue, optionally with a corresponding source code snippet that shows the issue.

heading Workaround

The Workaround section describes how to avoid running into the issue. This usually consists of rules that forbid certain code patterns.

heading Detection

The Detection section describes how to detect occurrences of this issue. This usually consists of instructions like looking for certain code patterns or strings.

heading Mitigation

The Mitigation section describes how to fix detected occurrences of the issue in a codebase. This usually consists of instructions on either removing the offending code patterns or replacing them with similar behaving constructs that do not invoke the issue.