Code style
This is the contributor contract for project-owned source and tests. It favors code whose intent, data flow and safety properties can be understood from the current interfaces. Generated, vendored and downloaded sources keep the style and constraints of their owner; small FPLinux adapters follow the boundary of the project they are compiled into.
Contributing has the commands for formatting, checking and testing; Build FPLinux covers target builds. Run the checks and affected builds that exercise the real language and runtime boundary of a change.
General principles
Section titled “General principles”Directory names
Section titled “Directory names”Use lowercase snake_case for Python package directories and lowercase kebab-case for project-owned resource, fixture and documentation directories. Target, profile and package identifiers also use kebab-case. A Python package has its own __init__.py; a directory containing standalone Python programs or data beside a Python module is not a package. For example, sources.py reads resources from sources/; those resources do not form an import package.
Keep the leading dot in metadata directories such as .github and .githooks. Preserve the prescribed source directory names LICENSES for REUSE and .github/ISSUE_TEMPLATE for GitHub. Platform and target linux/overlay/Documentation directories, including the platform target template, retain the Linux name; their children and neighboring resource directories still follow the resource policy. Generated or downloaded trees and paths reproduced inside test runtime filesystems retain their owner’s layout; do not rewrite those paths to match source-directory naming. File names follow their language or format rules.
./fplinux check source validates directory names from tracked and non-ignored source files, including resources and website assets. Rename a source directory and its consumers together; do not retain aliases or fallback lookups for the old spelling.
Make the main behavior obvious
Section titled “Make the main behavior obvious”Use names that state the operation and domain. Prefer explicit arguments, keyword arguments for otherwise ambiguous policy choices, and named intermediate values over compact expressions that hide ordering or errors. Separate preparation, execution and result collection when those steps have different effects or failure modes. A short helper with one caller is useful when it gives a meaningful name to such a boundary.
Keep public command construction readable. Sharing parser setup must not change accepted arguments, help text or dispatch behavior; the language guides give the parser rules. In shell command builders and TOML fixtures, make decisive inputs visible instead of burying them in positional lists or nested executable strings.
Keep a generated document’s structure and conditional sections readable together. Split text into external resources when they have a useful independent identity, such as a complete program or delivered document; line count alone is not a reason to split. The Python text and resource rules define section boundaries and substitutions.
Give shared behavior one owner
Section titled “Give shared behavior one owner”Share behavior when current consumers have the same inputs, results, error semantics, side effects and lifetime rules. Let callers supply real policy differences explicitly. Do not combine similar-looking operations when they serve different runtimes, durability guarantees, external ABIs or standalone delivery boundaries.
Use existing project code before adding a local copy; the Python guide covers shared helpers for file hashing, linker maps and atomic file publication. Keep a standalone program self-contained when importing project code would break how it is built or distributed.
Remove wrappers, duplicate validation and optional behavior that have no current consumer. Do not add a registry, mode switch or extension point for a possible future target. Preserve separate implementations when they express different policies or provide independent evidence.
Prefer an existing sufficient facility
Section titled “Prefer an existing sufficient facility”Look for a solution in this order:
- Existing code that already owns the behavior.
- The language standard library.
- The native kernel, POSIX or platform API for the relevant runtime.
- An installed project dependency.
- A small direct implementation.
Verify differences in accepted inputs, errors, side effects, resource lifetime and packaging before replacing custom code.
Preserve contracts and safety
Section titled “Preserve contracts and safety”Keep public CLI arguments, output, exit behavior, file formats and external ABI names stable unless the change explicitly updates that contract. Validation, range checks, atomic replacement, filesystem synchronization, resource cleanup and concurrency control are not incidental style: retain them where they protect data, hardware state or a supported workflow.
Make ownership and lifetime visible. Pair acquisition with cleanup, restore borrowed system state, and keep policy choices at the caller that owns them. Do not generalize a kernel, bootstrap, phone or host assumption across runtime boundaries without evidence that the other consumer supports it.
Comments and docstrings explain a non-obvious invariant, external constraint, safety property or interface. Do not narrate obvious statements or retain a history of refactors. Maintained documentation describes current supported behavior and links to the canonical owner of a workflow instead of copying it.
Language guides
Section titled “Language guides”- C covers the kernel, pre-Linux bootstrap, phone userspace, host tools, embedded adapters and C harnesses.
- Python covers the host CLI, build tooling and Python tests.
- Shell covers POSIX, Bash and OpenRC scripts, plus the separate Alpine
APKBUILDboundary. - Source formats covers canonical field order, meaningful sequences and template values.
Formatting is necessary but not sufficient. A formatted host compile does not establish an ARM, musl, kernel, bootstrap, package or physical-device result.
Python tests use pytest and its native assertions, fixtures and parameterization. See the Python test style and test command.
Test a stable behavior
Section titled “Test a stable behavior”Each test protects a consumer-visible behavior, invariant, error, safety property or public artifact. Its name should state the operation, material scenario and expected result. Before adding a case, identify the concrete regression that would stop being detected if the test were removed.
Exercise production code through a normal import, object link, process, public entry point or built artifact appropriate to the claim. Do not extract private functions with source or AST surgery, include a production C file directly in a harness, or parse source text and patches as a substitute for behavior.
Regression tests require a reachable failing scenario or direct causal proof, the violated contract and the observable harm before the fix. Test the restored behavior, not the spelling of the patch.
Keep the oracle independent
Section titled “Keep the oracle independent”Expected results come from a specification, literal example, independently trusted implementation or separately measured result. Do not calculate expected values with the production constant, registry, helper or algorithm that produces the actual value.
Share fixture construction, process control and comparison mechanics when that makes scenarios clearer, but keep decisive expected data independent. Binary FDT fixtures, for example, are constructed by test-owned format code rather than the production parser. Small C transformation cases use reviewable literal maps instead of copying the production transformation algorithm.
Reject change detectors that freeze a current source list, private call order, configuration spelling or implementation registry. An exact inventory belongs in a test only when the inventory itself is a public format, protocol, release manifest or security allowlist.
Make fixtures and execution readable
Section titled “Make fixtures and execution readable”Keep short decisive inputs and expectations beside the case. Store substantial configuration documents, expected documents and executable test peers in files owned by the relevant test domain. Test code names those files and shows the preparation, action and independent assertions; moving the same embedded document into another Python helper does not give it a separate owner.
A fixture states the resource it owns or the external boundary it replaces and exposes the values that matter to the assertion. Express its consumers through explicit fixture arguments instead of hidden test-instance state or setup mixins. A fixture may depend on another fixture when that relationship represents real preparation or lifetime. Keep automatic fixtures for invariants that apply to every case in their scope, and avoid a global fixture framework.
For process-heavy cases, use named preparation, execution and collection steps when they make resource ownership and failures easier to follow. Control paths, environment, locale, time, randomness and subprocess lifetime. Use unique temporary resources, support independent and parallel runs, and clean up only resources owned by the case.
Prefer real temporary files, processes, locks and production objects when they are deterministic and practical. Mock external, expensive, unavailable or nondeterministic boundaries. Do not mock the central subject and then assert that the mock was called; assert observable values, files, state transitions, messages, artifacts or effects instead.
State the evidence level
Section titled “State the evidence level”Pure units, host components, mocked integrations, package inspections, public workflows and physical hardware runs establish different facts. Test names, docstrings and reports must describe the boundary actually exercised. A host C harness is not a framebuffer or phone test, and a successful build is not a hardware test.
Keep tests hermetic and deterministic unless their declared purpose is to exercise an external integration. Tests must not silently depend on ambient credentials, a developer home directory, live network access, incidental cache, execution order or previous test results.