Clarify update rules for component interfaces

[isamu-takagi]

Overview

To scale Autoware development, we need to provide a stable interface. However, for development reasons, it may be necessary to change the interface. In order to minimize the impact of updating the interface, I would like to consider the interface update procedure, compatibility and migration.

Goals

• update rules for component interface
• version management
• compatibility and migration

Related links

• About Autoware interfaces
• AD API
• Define component interfaces
• Version manager

What is interface update

Here we define the following as an interface update. The "Compatibility" column indicates compatibility for source code. Note that it is not compatibility for ROSBAG etc. because the binary representation of ROSIDL is different

Name	Code Compatibility	Data Compatibility	Description
add interface (new message type)	yes	yes	Add topic or service.
add interface (existing message type)	yes	yes	Add topic or service.
remove interface	no	no	Remove topic or service.
change interface name	no	no	Rename topic or service.
change interface type	no	no	Change msg or srv.
add field	yes	no	Add field.
remove field	no	no	Remove field.
change field name	no	yes	Rename field.
change field type (compatible)	yes	no	Change field type (e.g. uint8 to uint16).
change field type (not compatible)	no	no	Change field type (e.g. uint16 to uint8).
change field type (used as enum)	yes	no	Change field type.
change field order	yes	no	Change field order.
add constant	yes	yes	Add constant.
remove constant	no	no	Remove constant.
change constant name	no	yes	Rename constant.
change constant type	no	no	Change constant type.
change constant value	yes	no	Change constant value.
change constant order	yes	yes	Change constant order.

[isamu-takagi]

One way is to forbid the incompatible change and create a new interface instead, and keep the old interface for a period of time.

• Pros
  • It doesn't affect your code at all.
• Cons
  • The interface is duplicated.
  • The interface type (msg or srv) is also duplicated.
• Others
  • Need to decide how long you want to keep the old interface.

[isamu-takagi]

This is a way to version both messages and topics. The bottom side is when old messages can be generated from new messages.

[evshary]

Out of curiosity, does the MessageDev really exist in Release v1?
I think it makes sense to have MessageDev in Develop for v2 and Develop for v3 but not sure why in Release v1.

Anyway, I think the design is quite nice and it only needs an extra converter while bumping to a new version.
Although it might increase the latency, I think it's acceptable.
Also, we could add some warning messages in the converter to warn users that MessageV1 will be EOL if they're using it.

[isamu-takagi]

Out of curiosity, does the MessageDev really exist in Release v1?

MessageDev is always provided for packages that follow the latest version. MessageV1 can be thought of as a snapshot of the MessageDev at the v1 release.

[isamu-takagi]

REP-2011 Evolving Message Types
https://discourse.ros.org/t/rfc-rep-2011-evolving-message-types/27006

[isamu-takagi]

We created new discussion of proposal for maintain interface compatibility.
https://github.com/orgs/autowarefoundation/discussions/3922

[isamu-takagi]

If you have any requests and use cases regarding interface updates, please post them in this thread.

[xmfcx]

@isamu-takagi thanks for working on this and opening up this discussion!

add interface (from the table)

Can you elaborate this further?

• Adding a new message type
• Publishing a new topic using an existing message type

add field
add constant

Adding a new field to an existing message would change its signature.
If compiled along with Autoware, it would still compile and work.

But there might be some ABI compatibility issues because of the changed signatures for pre-compiled/distributed old/new messages.

I've lived issue when trying to backport something in the ros2 messages.

• Backport feature Prism in SolidPrimitive.msg to Foxy ros2/common_interfaces#170 (comment)

Edit: I've just seen your remarks on this:

Note that it is not compatibility for ROSBAG etc. because the binary representation of ROSIDL is different

Maybe we should also add a column for ABI compatibility too.

[isamu-takagi]

@xmfcx Thank you. I updated the table.

Can you elaborate this further?

Add "new/exsiting message type" for "add interface".

Maybe we should also add a column for ABI compatibility too.

Add data compatibility column.