Skip to content

Source formats

Use the shared format and check commands. Both calculate the same canonical bytes. Formatting publishes selected files after every tool succeeds; checking compares the result without writing the source checkout. File permissions, unselected files and the source inventory are preserved.

Canonical order groups related fields by their role. Alphabetical order applies only to independent dictionaries identified below. Unknown and optional fields keep their values; missing fields are not added. Comments stay with their field or section, and license headers stay at the beginning. Formatting does not repair semantic errors or add hardware support.

Arrays and execution sequences retain their source order except for the two TOML cases below. This includes patches, copies, appends, tool recipes, object and link lists, workflow jobs and steps, issue questions and choices, navigation, plugins, extensions and palettes. Linux integration normalizes independent copies by destination when preparing sources; patch and append order remains significant.

Ordinary fields precede child tables. Child tables stay with their owner, and a nested array of tables stays with its parent record. Scalar values, hexadecimal spelling and template placeholders are preserved; Taplo owns spacing and wrapping.

Document sections use this order; absent sections are skipped:

Document Section order
Target platform, identity, NAND, display, display brightness, rootfs, bundle, Linux, bootstrap, adapter, device data, Bluetooth, audio profile, FM radio, WCN firmware, microSD
Platform identity, rootfs, bundle, U-Boot, Linux, bootstrap, runtime, host
Profile name, Linux root, rootfs, bootstrap, U-Boot, FIT, layout, storage, runtime
Source lock Direct-original records in source-ID order
Alpine lock release/branch/architecture/triplet, repositories, minirootfs, runtime, runtime additions, sysroot, package catalogue
Environment lock Kern, Alpine base, package selection, tools, ordered inputs
Loader asset lock FDL1

Target fields follow their consumer roles:

Table Field order
identity brand, product, hardware_codes, compatible
nand raw_device, id, raw_page_bytes, ecc_format
display panel, boot_font
display_brightness backlight, levels
rootfs, bundle packages
linux config_fragment, memory, dtb, debug_dtb, patches, additional_forbidden_dtb_markers, additional_forbidden_config, overlay, copies, appends, dt_config_checks
memory base, size
copy, append source, destination
linux.dt_config_checks path, compatible, property, config
bootstrap lcd_config, image, map, dtb_destination, record_prefix
adapter spi_mode, backlight_channels, backlight_level, exec_distance, session_name, boot_instructions
device_data parser, originals_parser
audio_profile speaker_vibration, speaker_from_headphones, headfree_headphones_only, firmware
firmware record source, destination, size, sha256
microsd linux_patches, bootstrap, U-Boot
microsd.bootstrap source, image, map
microsd.uboot defconfig, patches, copies

Platform identity uses vendor, soc, aliases, compatible. Linux groups source and toolchain, configuration, destinations and outputs, then patches, overlay, copies, appends and configuration checks. Bootstrap groups source and destination paths, files and patches, toolchain and build settings, load limits, copies and memory layout. Runtime groups the load address, adapter and USB identities. Host runtime tools precede tool recipes; recipe members precede nonempty copy tables. Empty copy arrays remain ordinary fields.

Platforms declare linux.dt_config_checks for shared hardware; targets may add the same array for board-specific devices. The build checks both lists against the compiled device tree and kernel configuration.

Profiles group root kind/filesystem/wait, package selection, boot kinds, resident and load ranges, storage partitions, then runtime transport and runnability. Their package arrays retain their order.

sources.lock.toml owns direct originals. Each source record groups version, name, url, algorithm, checksum and optional bytes, followed by source-specific metadata. Consumer locks select a source ID and retain their usage fields. The dependency guide describes acquisition and restoration; native npm and Alpine locks retain their exact dependency graphs.

The environment lock groups Kern, Alpine base, direct APK selection, tools and ordered inputs. Kern uses source, binary_sha256; the base uses source, arch. Selection uses arch, apk_groups. Named tools select an input; input records use key, purpose, arch, source. Input records, package groups and packages within those groups retain their order. The installation recipe reads these selections rather than repeating original URLs and checksums.

The platform loader asset lock’s [fdl1] uses source, path. Generated standalone asset locks retain their resolved source/output form.

Source records, independent source-file hash dictionaries, spelling identifier/word dictionaries, Alpine repositories and runtime additions use case-sensitive lexical key order. The two reordered array families are target and platform rootfs/bundle package sets, which use package-name order, and Alpine package records, which use filename order. Other arrays, including profile packages and Alpine runtime/sysroot packages, retain their order.

REUSE annotations retain their record and path order. Each annotation uses path, precedence, copyright, then license. Ruff configuration groups target version, line length, cache and exclusions, then lint and format settings. Mypy uses Python version, strictness, search path and cache path. Per-file lint rules retain their order.

JSON descriptions group schema, identity/version, description/type/license, contact and repository links, engines/package manager, scripts, dependency maps, hashes and settings. Dependency, hash and settings dictionaries use lexical key order. Arrays keep their order. JSONC comments are retained. The npm-owned package-lock.json remains outside source formatting.

YAML bindings use $id, $schema, title, maintainers, description, select, allOf, properties, pattern properties, required fields, dependencies, additional or unevaluated properties, then examples. Literal examples and scalar types are preserved.

Workflows group name, trigger, permissions, concurrency, environment/defaults and jobs. Job settings group dependencies and conditions, execution environment, permissions, environment and execution options, inputs/outputs, then steps. Steps group name/id/condition, uses or run, inputs, working directory, shell, environment and error/time limits. Job and step sequences are preserved.

Issue forms group name, description, title and assignment settings, then the body. Each item uses type, id, attributes and validations; attributes group label, description, placeholder/value, rendering and choices.

YAML field reordering uses block mappings without aliases. Prettier owns JSON and YAML layout.

Devicetree properties group device_type, compatible, reg, ranges, common properties, device-specific properties and status. Names inside a group use natural order. Complete property statements move together; values and arrays retain their bytes. Includes, preprocessing, node declarations, node additions and overrides retain their position. Ambiguous syntax remains in place.

APKBUILD declarations, shell commands, sources, subpackages and checksums retain their order. Makefile recipes, assignments, object and link lists also retain their order; Kconfig choices, defaults and help text are preserved. These formats and assembly receive only safe final-newline normalization. INI and EditorConfig declarations receive trailing-space normalization while section precedence and values remain unchanged.

C and headers use the existing Clang style with include sorting disabled. Python uses Ruff’s selected import-order fix and formatter. Recognized shell scripts keep their declared dialect and use shfmt.

Website JavaScript, TypeScript and Astro use the site’s Prettier configuration, with a preference for double quotes. Object keys use alphabetical order; arrays retain their order. When a consumer requires a particular property order, disable only sort-keys around that object and explain the requirement. Unused rule-disable comments are errors.

The site workflow owns formatting and type-aware checks for these files. Markdown code examples retain their original formatting.

MDX prose uses one physical line per paragraph or simple list item. Prettier removes soft line wrapping with proseWrap: "never"; use the editor’s visual word wrap for reading. Tables use one space around each pipe and short alignment markers, without padding cells to the width of a column. The configured formatter applies both rules automatically, and the site check rejects noncanonical formatting. Keep intentional line breaks, code blocks and table alignment semantics intact.

Separate ::: directive boundaries and Markdown prose inside block components from neighboring content with blank lines. These are structural boundaries, not line wrapping. Raw JSX retains its own whitespace rules; keep inline component markup on the paragraph’s line.

Supported .in templates use the same rules as their rendered format. Placeholder text is preserved.

A complete text resource owns its internal whitespace and final newline. Separators used only to join prose sections belong to the document renderer. Do not store leading or trailing blank lines in fragments solely to control the spacing of another document, and do not trim scripts, patches or exact test data through prose-formatting helpers.

Executable shell templates retain their shebang and use the same shell formatter and checker as ordinary scripts. A text template whose placeholders are not valid in the target syntax uses .txt.in; check its rendered document through the actual target parser or build tool.

Formatter and parser corpus files may deliberately contain noncanonical input or independent expected bytes. Give those data files a .fixture suffix and pass the intended logical source path explicitly in the test. They remain subject to general source-text and license checks, but the source formatter must not rewrite them. Keep short invalid byte sequences inline when their missing newline, encoding or whitespace is the property under test.