Add distro compatibility policy

[nbbrooks]

Description

Document the in-source patterns and process moveit2 uses to keep main building on every active ROS 2 distro, plus the lifecycle for adding and removing distros from the CI matrix. Three topics:

1. Supporting multiple distros on main — five sub-patterns covering C++ source divergence (RCLCPP_VERSION_GTE), package.xml conditional deps, launch-loaded file overrides, CMake feature detection, and MIGRATION.md updates.
2. Handling dependencies without a bloom package — CI source-build via per-distro .repos files (preferred), with a CMake-side optional feature-flag fallback.
3. CI matrix policy — add / graduate / drop lifecycle.

Each pattern carries a cleanup rule keyed on a distro EOL trigger, so the conditional code paths don't accumulate indefinitely.

Why now

We're accumulating multi-distro divergences in main without a written convention. Recent precedents that motivated this:

• #3567 uses the RCLCPP_VERSION_GTE pattern for C++ source divergence.
• moveit/moveit_resources#211 introduces format-3 condition= deps and a launch-time YAML override helper.

Capturing these as a single documented policy lets future divergences land consistently and gives reviewers a checklist.

Checklist

• Code is auto-formatted (documentation-only)
• Tutorials/documentation — not applicable; this is a contributor doc
• MIGRATION.md — not applicable; this is the policy that requires future MIGRATION.md entries
• Tests — not applicable
• GUI screenshots — not applicable

[rhaschke]

Thanks for explicitly writing that down. I only have a few minor comments:

• Place the file in doc/

[rhaschke]

When a package exists in rosdistro, it was bloomed. However, it might exist in ros-testing only, because it requires a sync. I suggest dropping the mention of bloom (here and below).

Suggested change

	When a moveit2 dependency is **released** for a distro (entry exists in `rolling/distribution.yaml`) but **not yet bloomed** to the apt binary repo, CI fails at `rosdep install`. Two complementary approaches handle this. **Prefer §2.1.**
	When a moveit2 dependency is not yet released for a distro, CI will fail at `rosdep install`. Two complementary approaches handle this. **Prefer §2.1.**

[rhaschke]

Add an else branch to inform users about the omitted feature (as required below).

Suggested change

	if(osqp_FOUND)
	add_subdirectory(online_signal_smoothing)
	target_compile_definitions(my_target PRIVATE MOVEIT_HAVE_OSQP)
	endif()
	if(osqp_FOUND)
	add_subdirectory(online_signal_smoothing)
	target_compile_definitions(my_target PRIVATE MOVEIT_HAVE_OSQP)
	else()
	message(STATUS "Dropping online_signal_smoothing as osqp wasn't found")
	endif()

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 46.30%. Comparing base (77c5894) to head (8d3ff57).
⚠️ Report is 10 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3751      +/-   ##
==========================================
+ Coverage   46.23%   46.30%   +0.08%     
==========================================
  Files         726      726              
  Lines       59501    59508       +7     
  Branches     7624     7623       -1     
==========================================
+ Hits        27505    27550      +45     
+ Misses      31829    31791      -38     
  Partials      167      167              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.