mirror of
https://github.com/PX4/PX4-Autopilot.git
synced 2026-11-22 14:19:57 +08:00
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>
2.6 KiB
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.cppis 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.mdthat 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.
longholds only whatshort,unit,min/max,default,reboot_required,requires_ethernetand the option labels don't already say. Omit it if nothing is left. Changeshortonly 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, oneLabel: effect.line per option. Never re-list the options inlong. - 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.