.pr_agent_auto_best_practices - iNavFlight/inav GitHub Wiki

Pattern 1: When changing the meaning of a filtered value, initialize and reset the filter in the new value's units. Refresh or reset its state when filtering is bypassed so re-enabling it cannot reuse stale data.

Example code before:

adjustmentFilter.reset(idleThrottle); // Filter now receives an adjustment.
if (smoothingEnabled) {
    adjustment = adjustmentFilter.apply(pitchAdjustment);
}

Example code after:

adjustmentFilter.reset(0); // Adjustment is zero-centered.
if (!smoothingEnabled) {
    adjustmentFilter.reset(pitchAdjustment);
    adjustment = pitchAdjustment;
} else {
    adjustment = adjustmentFilter.apply(pitchAdjustment);
}
Relevant past accepted suggestions:
Suggestion 1: [correctness] Re-enabling smoothing skews flight gains
Re-enabling smoothing skews flight gains `calculateFixedWingTPAFactor()` stops updating `fixedWingTpaFilter` while the time constant is zero, but does not reset it when smoothing is re-enabled. If a pilot changes the setting from nonzero to zero and back during flight, filtering resumes from the throttle value held before the zero setting, and that stale output affects the fixed-wing PID gains.

Issue description

The zero-time-constant bypass leaves the throttle filter's state stale when smoothing is later re-enabled in flight.

Fix Focus Areas

  • src/main/flight/pid.c[1335-1339]
  • src/main/fc/rc_adjustments.c[602-604]

Recommended Fix

Detect a transition from zero to nonzero time constant and initialize or reset the filter using the current compensated throttle before applying it. Preserve the unfiltered behavior while the time constant is zero.


Suggestion 2: [correctness] Fixed-wing gains are falsely attenuated
Fixed-wing gains are falsely attenuated `pidResetTPAFilter` still seeds `fixedWingTpaFilter` with the idle throttle value, while `tpaPitchThrottleAdjustment` now filters a zero-centered pitch adjustment and adds that result to the current throttle. With pitch compensation and throttle-based TPA enabled, initialization and repeated launch resets therefore begin near a +1000 adjustment, making the effective throttle approach its maximum and reducing fixed-wing gains until the default two-second filter converges.

Issue description

The fixed-wing TPA filter now processes a zero-centered pitch adjustment, but its lifecycle still initializes it with an absolute idle-throttle value and can preserve stale state while TPA is inactive.

Fix Focus Areas

  • src/main/flight/pid.c[467-472]
  • src/main/flight/pid.c[1300-1331]
  • src/main/navigation/navigation_fw_launch.c[318-322]

Recommended Fix

Reset fixedWingTpaFilter to zero now that its input is an adjustment rather than absolute throttle. Ensure its state is also updated or reset while pitch TPA is inactive so reactivation cannot reuse an adjustment from an earlier attitude.


Pattern 2: When recommending a new maintenance branch for pull requests, add it to the branch filters of workflows that build that branch or validate its changes.

Example code before:

on:
  pull_request:
    branches: [maintenance-10.x]

Example code after:

on:
  pull_request:
    branches: [maintenance-10.x, maintenance-11.x]
Relevant past accepted suggestions:
Suggestion 1: [correctness] Next-major changes get no nightly build
Next-major changes get no nightly build The branch suggestion now directs breaking changes to `maintenance-11.x`, but the nightly build's push trigger still lists branches only through `maintenance-10.x`. Commits pushed to the newly recommended branch therefore cannot produce nightly firmware artifacts through that workflow.

Issue description

The newly recommended maintenance-11.x branch is absent from the nightly build's push branches.

Fix Focus Areas

  • .github/workflows/pr-branch-suggestion.yml[25-25]
  • .github/workflows/nightly-build.yml[7-12]

Recommended Fix

Add maintenance-11.x to the nightly build's push branch list so commits to the recommended branch produce artifacts.


Suggestion 2: [correctness] Next-major pull requests skip version checks
Next-major pull requests skip version checks The suggestion sends breaking firmware changes to `maintenance-11.x`, but the parameter-group version check's pull-request trigger does not include that branch. A pull request targeting the recommended branch can change persisted parameter-group structures without running the repository's version-change check.

Issue description

Pull requests targeting the newly recommended maintenance-11.x branch do not trigger parameter-group version checking.

Fix Focus Areas

  • .github/workflows/pr-branch-suggestion.yml[25-25]
  • .github/workflows/pg-version-check.yml[4-13]

Recommended Fix

Add maintenance-11.x to the parameter-group version check's pull-request branch list.


Pattern 3: Derive SITL test executable paths from the configured project version, or provide a stable executable path, rather than hardcoding a versioned filename in test launchers.

Example code before:

simulator = "build/inav_9.1.0_SITL"

Example code after:

simulator = configured_sitl_executable()
Relevant past accepted suggestions:
Suggestion 1: [correctness] MAVLink SITL tests cannot start
MAVLink SITL tests cannot start The versioned SITL artifact changes from `inav_9.1.1_SITL` to `inav_10.0.0_SITL`, while the MAVLink mission, multi-port, and sanity test configurations retain the old path. After a clean 10.0.0 build, the mission runner exits on its missing-file check and the Python tests attempt to launch a nonexistent executable.

Issue description

The version bump changes the generated SITL executable from inav_9.1.1_SITL to inav_10.0.0_SITL, but checked-in MAVLink test launchers still use the old path, so those tests fail after a clean build.

Fix Focus Areas

  • src/test/mavlink/missions/run_mavlink_mission_tester.sh[10-10]
  • src/test/mavlink/ports/test_config_multiport4_sweep_rc460800_tele115200.yaml[2-2]
  • src/test/mavlink/sanity/mavlink_sitl_sanity.yaml[2-2]

Recommended Fix

Replace the hardcoded inav_9.1.1_SITL references with a version-independent path or update them to the generated inav_10.0.0_SITL artifact. Prefer deriving the path from the configured project version so future version bumps do not leave these test entry points stale, then run the affected MAVLink SITL tests.


Suggestion 2: [correctness] Three tests cannot start the simulator
Three tests cannot start the simulator `project(INAV VERSION 9.1.1)` changes `FIRMWARE_VERSION`, which `cmake/sitl.cmake` embeds in the executable name, while three runnable test configurations still request `inav_9.1.0_SITL`. After a clean build, the mission launcher fails its file check and the sanity and multi-port runners pass a nonexistent path to their process launchers.

Issue description

The project version bump renames the generated simulator executable, but operational test launchers and configurations still point at the previous versioned filename.

Fix Focus Areas

  • CMakeLists.txt[56-76]
  • cmake/sitl.cmake[124-124]
  • src/test/mavlink/missions/run_mavlink_mission_tester.sh[10-10]
  • src/test/mavlink/missions/run_mavlink_mission_tester.sh[146-162]
  • src/test/mavlink/sanity/mavlink_sitl_sanity.yaml[2-2]
  • src/test/mavlink/ports/test_config_multiport4_sweep_rc460800_tele115200.yaml[2-2]

Recommended Fix

Update all operational simulator paths to the 9.1.1 executable and preferably derive or discover the filename from the CMake project version so future version bumps do not break these test runners.


Pattern 4: For warnings explicitly about battery voltage, use voltage-specific thresholds or state rather than the aggregate battery state, which may represent remaining capacity.

Example code before:

voltageWarning = getBatteryState() >= BATTERY_WARNING;

Example code after:

voltageWarning = getBatteryVoltageState() >= BATTERY_WARNING;
Relevant past accepted suggestions:
Suggestion 1: [correctness] Capacity triggers voltage warning
Capacity triggers voltage warning When capacity thresholds are enabled, `getBatteryState()` returns capacity-derived state, so the multifunction voltage warning duplicates the capacity warning and can report `VBATT LOW/LAND` despite healthy voltage. It can also omit a genuine low-voltage warning while remaining capacity is healthy.

Issue description

Preserve voltage-specific warning semantics while avoiding references to checkBatteryVoltageState() on builds without USE_ADC. The aggregate getBatteryState() must not drive the explicitly voltage-based warning because it becomes capacity-derived when capacity thresholds are active.

Issue Context

batteryUpdate() selects checkBatteryCapacityState() when batteryUseCapacityThresholds is true. The following capacity-warning block already reports that aggregate state separately, so using it for the voltage block produces incorrect and duplicate warnings.

Fix Focus Areas

  • src/main/fc/multifunction.c[268-280]
  • src/main/sensors/battery.c[397-435]
  • src/main/sensors/battery.c[498-510]

Suggestion 2: [correctness] Capacity controls voltage blinking
Capacity controls voltage blinking When capacity thresholds are enabled, `getBatteryState()` makes the displayed voltage blink according to remaining capacity rather than the voltage thresholds. Consequently, healthy voltage can blink on low capacity while genuinely low voltage may not blink when capacity remains healthy.

Issue description

Keep voltage-display blinking based on voltage thresholds while preventing non-ADC builds from referencing an unavailable symbol. Do not substitute the aggregate battery state because it can represent remaining capacity.

Issue Context

checkBatteryVoltageState() evaluates batteryWarningVoltage and batteryCriticalVoltage, but getBatteryState() returns the shared state that batteryUpdate() derives from capacity whenever capacity thresholds are enabled. Use compile-time guarding or an always-defined voltage-state API with an appropriate non-ADC fallback.

Fix Focus Areas

  • src/main/io/osd.c[1588-1607]
  • src/main/sensors/battery.c[397-435]
  • src/main/sensors/battery.c[498-510]
  • src/main/sensors/battery.h[76-80]

Pattern 5: When adding fields to persisted parameter groups, update their registered version and provide a migration when the old and new layouts cannot be mapped by a prefix copy; if the payload exceeds storage limits, apply the required storage-layout migration too.

Example code before:

REGISTER_GROUP(settings, 3); // Persisted array shape changed.
loadByPrefixCopy(oldPayload, settings);

Example code after:

REGISTER_GROUP(settings, 4);
if (storedVersion == 3) {
    migrateEachOldArrayRow(oldPayload, settings);
}
Relevant past accepted suggestions:
Suggestion 1: [correctness] Upgrade corrupts alternate layouts
Upgrade corrupts alternate layouts Appending `OSD_TERRAIN_AGL` changes every row's stride in the persisted two-dimensional `item_pos` array, but the unchanged parameter-group version causes old bytes to be copied directly into the enlarged structure. After upgrade, layout 0's first value is consumed as the new terrain slot and every subsequent alternate-layout item is shifted, changing positions/visibility and assigning values to the wrong OSD elements.

Issue description

Adding an item changes the stride of each row in persisted item_pos[OSD_LAYOUT_COUNT][OSD_ITEM_COUNT]. Because the registered PG version remains 3, old four-layout payloads are copied as a flat prefix into the new shape and alternate layouts become misaligned.

Issue Context

The generic PG loader only performs a size-limited memcpy when versions match; it does not migrate two-dimensional arrays. Either bump the layout PG version so incompatible data resets safely, or add an explicit migration that copies each old layout row into the matching new row and initializes the Terrain AGL slot.

Fix Focus Areas

  • src/main/io/osd.h[382-383]
  • src/main/io/osd.c[235-236]

Suggestion 2: [correctness] Stale branch base reset
Stale branch base reset `ConditionStack.closed` remains valid after intervening enumerators, so a later opposite-polarity block for the same symbol is incorrectly treated as the prior block's alternate and resets `current_numeric` to a stale base. For example, after `A, #ifdef X B, #endif C = 10, #ifndef X D`, this PR emits `D` as `(1)` instead of the correct `(11)`, whereas the old sequential counter handled the explicit reset correctly.

Issue description

The sibling-branch cache survives ordinary enum members, causing a later opposite-polarity conditional to reuse a stale numeric base even though the two blocks are not adjacent alternate branches.

Issue Context

Only an immediately corresponding opposite-polarity sibling should reuse the closed branch base. Parsing any intervening enumerator must invalidate the closed frame at that nesting level; add regression coverage including an intervening explicit assignment.

Fix Focus Areas

  • docs/development/msp/gen_enum_md.py[107-114]
  • docs/development/msp/gen_enum_md.py[262-297]

Suggestion 3: [correctness] Circular radius omission accepted
Circular radius omission accepted `MSP2_INAV_SET_GEOZONE_VERTEX` now accepts a 10–13 byte payload for a circular zone, writes the center, skips the required 4-byte radius, and returns success. The resulting circular geozone retains no newly supplied radius (or a stale prior one), so enforcement can use an unintended boundary.

Issue description

MSP2_INAV_SET_GEOZONE_VERTEX accepts a circular-zone payload without the required four-byte radius, mutates the center, and reports success.

Issue Context

Polygon updates require a 10-byte prefix, while circular updates require that prefix plus a 4-byte radius. Preserve lenient acceptance of bytes beyond the known complete encoding, but reject circular payloads shorter than 14 bytes before mutating vertex state.

Fix Focus Areas

  • src/main/fc/fc_msp.c[3922-3936]

[Auto-generated best practices - 2026-11-02]

⚠️ **GitHub.com Fallback** ⚠️