search

ros / joint_state_publisher

http://wiki.ros.org/joint_state_publisher
50 stars 81 forks source link

Update docs regarding GUI changes #46

Closed peci1 closed 4 years ago

peci1 commented 4 years ago

@clalancette could you please update the wiki entry with up-to-date information about how to use the GUI?

This big change has not been documented enough, and that's bad! There is a discourse thread, which is good, but e.g. from our 20-people team, I'm the only one reading discourse. Yes, there is a warning issued by the code, but well, as we all know, warnings can get lost quite quickly when launching a larger system.

I'd expect an update of the ROS wiki, probably with some pretty big bold text that would tell the users what happened (at least on kinetic and melodic subpages). I'd also expect an example on how to transform old code to new one (most importantly the needed change to package.xml).

Further, it's become quite standard to provide a MIGRATION.md file listing breaking changes. Please, add this one, too. And I can even imagine an entry in http://wiki.ros.org/melodic/Migration, although it is not really related to the switch to Melodic. And definitely, it should appear at http://wiki.ros.org/noetic/Migration .

The current warning message issued when running with the use_gui parameter is:

The 'use_gui' parameter was specified, which is deprecated. We'll attempt to find and run the GUI, but if this fails you should install the 'joint_state_publisher_gui' package instead and run that. This backwards compatibility option will be removed in Noetic.

It'd help in fixing existing code if there were a direct link to the wiki explaining what has to be changed. The current warning tells users to manually install the GUI package, but that's not the correct solution (adding exec_depend is).

Just please, make the transition for users as smooth and easy as possible.

clalancette commented 4 years ago

Thanks for the feedback. I've now updated the wiki page for joint_state_publisher, and added a note to the Noetic migration notes.

I did not add a MIGRATION.md; if users aren't reading discourse and aren't reading the warning messages coming on the console, I'm highly sceptical that they'll read documentation in the source repository.

I'm going to close this, but feel free to reopen if you'd like to see more. Also feel free to edit the wiki pages yourself with information that may be useful to your users.

peci1 commented 4 years ago

Thanks, this looks good.