Pull Request Overview

Tock has something like 150 crates and 2200 source files, and the expectations for those files, in terms of importance to the OS, scrutiny in development, expectations for code review, and consensus needed to make changes, differ widely. Those expectations are largely implicit, with the understanding being based on convention, conversations in PRs, rough implications based on crate name/location, developer preference, rate of patches, importance to the threat model, and the impact of any bugs. This is hard for everyone to understand from the core team to new contributors. Having this be implicit leads to issues and can lead to issues, including:

• PRs taking much longer to review than contributors expect, because of a change to a "sensitive" file.
• Reasonable looking changes being rejected because they potentially reintroduce problems to bug-prone subsystems.
• PR reviewers having difficulty reviewing large changes, and not properly scrutinizing changes to "sensitive" files that are lost in changes to many files.
• Board developers not understanding which code is well tested/trusted, and which code is experimental.
• Changes to experimental subsystems taking too long because it isn't clear to reviewers the subsystem is experimental.
• Contributors not realizing a change is unlikely to be accepted, and then building other code on the assumption that original change will be accepted.

This TRD proposes "code tiers" which is a mechanism to explicitly annotate Tock source code with a tier indicating how scrutinized and trusted the code is. This should make the implicit understanding we have today more explicit. Eventually, developers and reviewers should be able to use these tiers to better understand how changes will affect the Tock code base.

rendered

Testing Strategy

n/a

TODO or Help Wanted

The first opening of this PR is intended to socialize the idea and gather feedback. As of the original opening, we don't have a prototype of exactly what these annotations would look like.

Documentation Updated

• Updated the relevant files in /docs, or no updates are required.

Formatting

• Ran make prepush.