Files
PX4-Autopilot/.github/instructions/parameters.instructions.md
T
Ahmet Burak Tektas 860481d8a1 docs(instructions): require an upgrade path for removed parameters (#29637)
A released parameter removed without a translation loses its stored value
on upgrade, and nothing in review flags it. EKF2_AGP_*, SENS_IMU_TEMP* and
FD_ACT_* went this way, and their translations and upgrade notes came in
later PRs. Add the rule to the parameter guidelines, which the AI review
loads for src/**.

Assisted-by: Claude:claude-opus-5-5

Signed-off-by: A.Burak Tektas <15087318+Abtektas@users.noreply.github.com>
2026-11-05 10:00:30 -07:00

2.6 KiB

applyTo
applyTo
src/**,ROMFS/**,boards/**

Parameter Guidelines

In addition to the core code review guidelines:

  • Each parameter has one owner: the module that owns the concept. Name and describe it by what that module does with it.
  • A module that needs another module's result consumes it on uORB instead of reading that module's thresholds and recomputing it. Shared vehicle configuration read by several modules (e.g. NAV_ACC_RAD) is existing practice; the rule targets coupling to another module's internal decisions.
  • No two parameters with the same meaning in different modules. Two concepts that shared one parameter are not duplicates: when logic moves between modules, split the parameter along the concepts, each named and described for its own role, rather than replacing one side with a hardcoded constant.
  • src/lib/parameters/param_translation.cpp is for parameters whose name or meaning differs from the last release. Renames and changes within the unreleased development window need no translation. When a released parameter splits into two, keep it and copy its value to the new one on import, so tuned setups keep both behaviours.
  • Removing a parameter that exists in the last release needs a translation, or an entry in the Upgrade Guide of docs/en/releases/main.md that says why there is none and what to set instead.

Descriptions

Descriptions ship xz-compressed in ROMFS on boards without CONSTRAINED_FLASH, so every word costs flash.

  • long holds only what short, unit, min/max, default, reboot_required, requires_ethernet and the option labels don't already say. Omit it if nothing is left. Change short only when it is wrong or repeats the type.
  • A few words of option detail go in the option's label, in parentheses. More goes in long, one Label: effect. line per option. Never re-list the options in long.
  • Keep every fact that affects configuration: behaviour, conditions, dependencies, limits, warnings. Cut restatements, "This parameter…", "Note that…", examples that repeat the rule, and rationale that doesn't change the value picked.
  • Wording already used in other descriptions costs almost nothing after compression; new wording costs full price. Use the stock phrases "Set to 0 to disable.", "Set to -1 to disable.", "Only used when X is enabled." and "e.g.", and refer to parameters by name.
  • Plain words in full sentences. No invented abbreviations or symbols as words (<=, =, / for "or").
  • Prose is one paragraph in a plain or quoted YAML scalar. Newlines reach QGC unchanged, so a | block wrapped mid-sentence shows broken lines. Use newlines only between per-option lines.