The document here https://github.com/flutter/cocoon/blob/main/CI_YAML.md should list and describe all fields and properties that can appear in a ci_yaml file, what they mean and how they affect what runs on CI, and what their default values are when they aren't explicitly provide.

In particular the flutter/engine names these fields and properties in its .ci.yaml file, which aren't mentioned or fully described in the docs:

• platform_properties:
  • device_type appears in the list of properties of a platform_properties and also appears as an element of drone_dimensions.
  • cores is listed as a property under platform_properties, but is not documented.
• targets
  • The docs for properties say that "any special values must be JSON encoded", but it's not clear what would make a value special. The docs also say, "Values are parsed to their closest data model" but there are no pointers to what that might mean.
  • The config_name property is not documented. Some targets have one and some don't (e.g. "Linux builder_cache"). What is the default value?
  • runIf and runIfNot are misspelled as run_if and run_if_not.
  • cache_name, cache_path, cache_paths, ignore_cache_paths, gclient_variables are not documented.
  • add_recipes_cq - What is the default when it is not specified explicitly?
  • build_fuchsia - Not documented. What is the default value?
  • fuchsia_ctl_version - Not documented. What is the default value?
  • clobber - Not documented. What is the default value?
  • emulator_arch - Not documented. What is the default value?
  • enable_cso - Not documented. What is the default value?
  • release_build - Not documented. What is the default value?
  • cores - Not documented. What is the default value?
  • framework - Not documented. What is the default value?
  • no_goma - Not documented. Why not goma and set it to false? What is the default value?
  • shard - Not documented. What is the default value?
  • subshards - Not documented. What is the default value?

There is confusing overlap in how to specify the machine type to run on:

• platform_properties can specify os, device_type, and cores.
• targets have fields drone_dimensions, and dimensions, which can specify the os and VM type(?).
• A target's properties list can also have fields drone_dimensions, cores, and cpu.

It's not clear from the docs when to use or not use these fields.