Changing Messages and Services

Do not change messages or services unless there is no other way. The definitions in common-interfaces (cpm_lab_lab_msgs, cpm_lab_map_msgs, cpm_lab_control_flow_msgs, cpm_lab_evaluation_msgs, cpm_lab_commonroad_msgs) are the contract between parts of the lab that are updated at different times:

  • muCars: the vehicle controller is cross-compiled and deployed separately (see muCar). A controller with other message definitions than the central workstation cannot talk to it; ROS2 does not even report an error, the messages simply do not arrive.

  • Motion planners of students and partner labs are built against the installed release and break with every change.

  • Recordings contain the message types of their release. cpm_eval reads them with the installed definitions, so old recordings can become unreadable, see Design: Recording and Evaluation.

  • Lichtblick extensions, the Control Center and the documentation (Interface Reference) all mirror the messages.

Before You Change a Message

Check the alternatives first:

  1. Use an existing field or message, e.g. a SystemTrigger type or the source_id.

  2. Add a parameter, a new topic or a new service instead of changing an existing one.

  3. Keep data that only one component needs inside that component.

Discuss the change with the team in an issue before you implement it, and plan it for a release, never as a hotfix.

If a Change Is Unavoidable

  • Only add: add new fields or constants at the end and give them a meaningful default (zero). Never rename, retype, reorder or remove a field or constant, and never change the meaning or unit of an existing one. Mark obsolete fields as deprecated in the comment instead of removing them.

  • One release: change the message, every publisher and subscriber in all components, the vehicle controller, the Lichtblick extensions, cpm_eval and Interface Reference in the same release.

  • Changelog: add an entry to the Forthcoming section of the message package and of the lab workspace that says Interface change and what users have to do, e.g. rebuild their planner.

  • Deploy together: after the release, update the central workstation, all muCars (Versions, Updates and Rollback) and Lichtblick at the same time. Mixed versions are not supported.

  • Recordings: state in the changelog whether recordings of older releases can still be evaluated. If not, keep an installation (e.g. a desktop image) of the old release to evaluate them.