chore(cli): improve warnings

[Tieske]

2 commits;

• describe changes when switching to new commands
• diplay message when reading from stdin

EDIT: 2nd commit moved here: Kong/go-database-reconciler#17

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 0% with 39 lines in your changes missing coverage. Please review.

Project coverage is 5.91%. Comparing base (fdb5b59) to head (2486281).
Report is 163 commits behind head on main.

Files with missing lines	Patch %	Lines
cmd/gateway_validate.go	0.00%	9 Missing ⚠️
cmd/gateway_diff.go	0.00%	7 Missing ⚠️
cmd/file_convert.go	0.00%	6 Missing ⚠️
cmd/gateway_sync.go	0.00%	6 Missing ⚠️
cmd/gateway_dump.go	0.00%	5 Missing ⚠️
cmd/gateway_ping.go	0.00%	3 Missing ⚠️
cmd/gateway_reset.go	0.00%	3 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##            main   #1115      +/-   ##
========================================
- Coverage   5.95%   5.91%   -0.04%     
========================================
  Files         31      31              
  Lines       3126    3144      +18     
========================================
  Hits         186     186              
- Misses      2930    2948      +18     
  Partials      10      10              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[mheap]

Based on feedback so far I think we should keep -s as the default, even in the new aliases. It should be a 1:1 implementation for the existing command (with positional arguments in place so that we don't break BC for people that already migrated).

With that in mind, this PR provides inaccurate guidance and shouldn't be merged.

[rspurgeon]

As discussed, let's make -s/--state and positional arguments for the gateway commands both supported and I think we should change the documentation to say something like the following that indicates why a user may want to switch from the -s to positional:

Use 'deck gateway diff' instead.
Note:
  - see 'deck gateway diff --help' for changes to the command\n"+
  - The new command supports the '-s/--state' flag for backward compatibility but also supports specifying state files as positional arguments which allows for alternative shell expansions (`*.yaml`).

[mheap]

We shouldn’t provide two ways to do the same thing long term. If positional arguments are the future, then the PR is ok, but I’d like @hbagdi to sign off. We chose flags for a reason in the original design

[rspurgeon]

My feedback is driven to help a user understand the differences in capabilities of the two options, which it seems we have established are staying in the tool (-s to maintain BC and positional to maintain BC with early adopters). IIUC the two options provide different capabilities on the shell, so we should document that.

[RobSerafini]

@Tieske Is the CI failing because you tried to remove code coverage from the CI? Can we separate the warnings work from the code coverage change?

[Tieske]

@RobSerafini just flaky CI

[rspurgeon]

Here is the change that needs to occur with the current deprecation messages for all commands that have been marked deprecated by this change.

Currently the messages read as follows:

Warning: 'deck sync' is DEPRECATED and will be removed in a future version. Use 'deck gateway sync' instead.

These will change to:

Info: 'deck sync' functionality has moved to `deck gateway sync` and will be removed in a future MAJOR version of deck. Migration to `deck gateway sync` is recommended.
    Note:
        - see 'deck gateway sync --help' for changes to the command
	- files changed to positional arguments without the '-s/--state' flag
	- the default changed from 'kong.yaml' to '-' (stdin/stdout)

[rspurgeon]

lgtm

[rspurgeon]

@Kong/team-deck can we get this merged in and a release built? tag @teb510

[RobSerafini]

@mikefero @mflendrich - I think this just needs an approval and merge and a new build of Deck. Can you guys help move this along?

[GGabriele]

Added a minor comment. Otherwise, LGTM