Additional information about each Step

[xaocon]

There are a lot of steps (which is great) but it's can be difficult to parse what some of them do. I noticed it with Wsl vs WslUpdate but I noticed there was also some confusion with Gems #346. I think there needs to be some more documentation/information about what each step is and/or does.

I'm not really sure what the best way to go about it is though. I think it would be best if a person didn't need a browser to get the details. I've thought a bit about having it in the config file example but in many cases it doesn't fit neatly in with the config options so there might need to be change to the config layout (not great but maybe worth it or you're considering an overhaul anyways) or it would just be regular documentation shoved into comments of the config file.

The other option I see is building it into the cli options. Maybe a subcommand or flag that took an optional step name that would print out some relevant info. It could be tuned to the platform it's running on, maybe even generated from doc blocks or something.

Maybe you could share your thoughts and I could see if there's some way that I could help.

[SteveLauC]

Yeah, I think such information is needed, Topgrade indeed has a lot of steps supported!

I think it would be best if a person didn't need a browser to get the details.

I think we can go with a cli option, like:

$ topgrade --info-step # no argument provided, print all the steps in a list

$ topgrade --info-step shell # print the detailed info about shell

I think we need to figure out what should be provided in the information? Maybe:

• Website
• Description
• and more?

[xaocon]

Yeah, I think that's on the right track. Maybe some relevant information about how the step can be configured as well? I'm thinking something like pointing out wsl_update_pre_release and wsl_update_use_web_download for WslUpdate as an example.

[SteveLauC]

I'm thinking something like pointing out wsl_update_pre_release and wsl_update_use_web_download for WslUpdate as an example.

Currently, I try to document configuration entries in the example configuration fileexample.config.toml, and the sections in the configuration file and steps do not correspond, which means that we need to maintain them separately if we are going to implement this.

Though I think we can do something like:

$ topgrade --info-step wsl_update
- Update WSL itself
- Available config options:
  * windows.wsl_update_pre_release
  * windows.wsl_update_use_web_download

[SteveLauC]

Convert this to an issue