[docs] clarify when to use `message` and when to use `progress(..., permanent=True)`

canonical / craft-cli

https://canonical-craft-cli.readthedocs-hosted.com/en/latest/

GNU Lesser General Public License v3.0

9 stars 14 forks source link

[docs] clarify when to use `message` and when to use `progress(..., permanent=True)` #248

Open lengau opened 3 months ago

lengau commented 3 months ago

What needs to get done

Clarify when a developer should use message or when they should use progress.

Example: Which is the correct way to show a warning?

Why it needs to get done

User confusion: https://github.com/canonical/craft-application/pull/302#discussion_r1562935131

mr-cal commented 1 month ago

As discussed as a team, emit.message() should only be used for the real output of a command.

For example, snapcraft plugins should use emit.progress(permanent=True) for the deprecation notice to use snapcraft list-plugins and emit.message() to print the list of plugins.

Assigning this to @tigarmo, who is going to clarify this in the docs.

Long-term, the correct path forward will be https://github.com/canonical/craft-cli/issues/256