FIDL project checklist

Changes to FIDL can often have a large number of downstream effects. This document provides checklists for items that should be considered when changing FIDL. Note that not all elements of the checklist will necessarily apply to every change, but they should at least be helpful for developers to double check that their changes are complete.

Changes to the fidlc compiler

This checklist is for changes that affect FIDL itself, such as syntax or semantics changes.

• Update specifications.
  • Language reference and code snippets where applicable.
  • FIDL grammar.
  • Bindings spec for guidance for how backends should generate code for this feature.
  • When appropriate, update the lexicon.
• Update associated tools.
  • The FIDL formatter/linter and their associated TreeVisitors.
  • The fidldoc tool, for language changes that should be reflected in the generated documentation, e.g. a new data type or modifier.
  • Editors and syntax highlighting.
• Update FIDL files. For syntax changes, update existing FIDL source including:
  • Actual FIDL source files in tree (and out of tree, if required).
  • FIDL source specified as strings in test source code, such as the compiler unit tests and the fidlgen end-to-end tests.
  • FIDL snippets in documentation.
• Ensure that interactions with attributes are handled.
  • For example, does the feature require a new placement?
• Update integration tests
  • For larger language features, it may be worth adding test coverage in existing integration tests. For example, ensuring cross binding consistency through the compatibility tests, or transitionability through the source compatibility tests.
• For parser changes specifically:
  • Update the span_tests to ensure that the parsed spans are correct, and not just that parsing succeeds
• For raw AST changes:
  • Ensure updates to the AST are propagated to the raw AST tree visitor and its downstream users as well. For example, adding a new field to a node probably should be accompanied with a visitor change that visits that new field.
• For semantics changes:
  • Update the feature specific unittest, e.g. table_tests when making a modification to tables, or create a new test file.

It is expected for changes to FIDL which cascade to backends to update all Fuchsia FIDL team owned bindings, i.e. Rust, Go, Dart, HLCPP, New C++ (natural and wire).

Changes to the JSON IR

• Ensure that the change is reflected by a change in the IR goldens.
• Update the JSON schema.
• Update any JSON consumers, including:
  • fidlgen lib
  • fidl codec
  • fidlmerge
  • fidldoc
  • banjo
  • measure-tape
  • GIDL
  • zither
  • summarize

Changes to fidlgen_<lang> backends

• Update the bindings docs if the generated code has changed.
• Update the bindings tutorials to reflect the current best practices and patterns.
  • Incorporate example code which compiles and runs in the build (e.g. //examples/fidl/go/fidl_packages/fidl_test.go).
• Update any relevant guides:
  • FIDL API rubric for guidance on using this feature.
  • For example, when changing the memory allocation APIs in C++ wire types, the C++ wire domain object memory ownership guide should be updated.
  • We've also found it good practice to present to API Council in order to socialize new features, and explain to council members how to review APIs in light of evolutions.
• If changing bindings API, update GIDL backends to use the updated API.
• If changing behavior or adding dynamic features, update client and server dynamic test suites.

Changes to the FIDL wire format

• Update the bindings to support the new wire format.
• Update the wire format specification to document the new wire format.
• Update measure-tape to support size calculation in new wire format.
• Update fidl-codec to support encoding/decoding in the new wire format.
• Update targets which have to manually encode/decode FIDL (the following list and reasons was reviewed on Feb 2023):
  • userboot: as the first userspace process, it cannot use mutable data segment, cannot use RELRO, and cannot use thread local storage. The lack of RELRO precludes const global/static variables whose initializer contains non-NULL pointer values, which rules out many libraries including FIDL bindings. This will be addressed by https://fxbug.dev/42072759.
  • ldmsg: used by the C library to load libraries during process startup. It cannot use full-fledged FIDL bindings due to sanitizer ABI requirements. This will be addressed by https://fxbug.dev/42072830.
  • libc sanitizers/debugdata: the sanitizer support libraries themselves cannot use functions built with sanitizers. This will be addressed by https://fxbug.dev/42072760.

Horizontal testing requirements

Add coverage to:

• The at-rest conformance suite.
• The dynamic compatibility suite.
• The dynamic client suite and server suite.
• The dangerous identifiers suite.