So I have some ideas for changes which would be reflected in the migration guide and would make it easier to translate between ROS API's. I wanted to get feedback on them before opening a pull request for each:

• Provide a version of create_publisher (and others) which take queue_size instead of a QoS struct.

Internally this function would get the default QoS struct, change the queue_size, and then call the current methods.

Example of how the migration guide would then look:

//  ros::Publisher chatter_pub = n.advertise<std_msgs::String>("chatter", 1000);
//  ros::Rate loop_rate(10);
  auto chatter_pub = node->create_publisher<std_msgs::msg::String>("chatter", 1000);
  rclcpp::rate::Rate loop_rate(10);

• Done in add create_publisher signature which takes just a queue size rclcpp#125
• For subscriptions too: add version of create_subscription which just takes queue size and not a qos profile rclcpp#128 and add a test which uses the create_subscription with queue size api system_tests#56

• Use advertise instead of create_publisher and subscribe instead of create_subscription.

I'm sort of agnostic about this, but it might help conceptually in the transition.

Example:

//  ros::Publisher chatter_pub = n.advertise<std_msgs::String>("chatter", 1000);
//  ros::Rate loop_rate(10);
  auto chatter_pub = node->advertise<std_msgs::msg::String>("chatter", 1000);
  rclcpp::rate::Rate loop_rate(10);

We could also provide an alias from one to the other, but then we make the API bigger, so maybe not.

A little rational for the new name is that in C we need a create/destroy pair, and create_publiser/destroy_publisher made more sense than advertise/destroy_publisher.
Using the same name in C++ was just for consistency.

• Provide versions of publish and signatures of callbacks which take const references rather than smart pointers.

This would be in addition to what's there, it would affect the guide as such:

//  std_msgs::String msg;
  std_msgs::msg::String msg;

//    msg.data = ss.str();
    msg.data = ss.str();

//    ROS_INFO("%s", msg.data.c_str());
    printf("%s\n", msg.data.c_str());

• Finished in small changes to make the publish const reference api work rclcpp#127
• Tested in added a test for publishers which uses the const reference api system_tests#55