Determine phrasing of deprecation messages for the `apollo` CLI

[abernix]

Description

Since the rover CLI is offering the new experiences that were previously offered through the apollo CLI's service commands (documented below; which will be deprecated in a future version), we should start raising awareness to rover from the invocation of the commands in the old CLI as soon as possible. This will allow our users to get exposure / awareness to the new experience (and provide feedback on it) as soon as possible and make this more graceful than merely a major breaking change in apollo.

We should align on the messaging for those messages! (One could argue that the actual implementation ticket for what we agree on should be opened in the apollo-tooling repository, but getting alignment from this team here first seems prudent, to me. Happy to adjust!)

The precision in which the new workflows should be applied is best covered by the migration guide, but — briefly — the commands which necessitate the messaging treatment are:

• apollo service:check 👉 rover subgraph check
• apollo service:delete 👉 rover subgraph delete
• apollo service:download 👉 rover graph introspect
• apollo service:list 👉 rover subgraph list
• apollo service:push 👉 rover graph publish or rover subgraph publish. When needing to introspect a running service (e.g., via --endpoint in the apollo CLI), there are now (respectively) rover graph introspect and rover subgraph introspect commands. (See migration guide!)

I've consulted with the commands list on apollo-tooling to identify this list, but again I cannot stress enough the nuances of this migration are best covered by the migration guide linked above!

Does this sound like an okay plan? If so, some messaging discussion seems appropriate.

[EverlastingBugstopper]

This plan sounds good! I honestly don't think we'd even need to duplicate the info in the migration guide in the output here, I'd be happy with just a link to the migration guide.

I'd propose a warning on stderr pretty close to the first thing we print out for each of those commands with something along the lines of this:

$ apollo service:check .......
WARN: This CLI will soon be deprecated, for help migrating to Apollo's new CLI tool Rover, check out the official migration guide:
WARN: https://www.apollographql.com/docs/rover/migration/

[abernix]

Yeah, agree with referring folks to migration guide and using stderr to convey it (to avoid breaking capturing of that in any stdoutput expectations).

I might suggest something service: command-specific rather than a CLI "umbrella" deprecation message, while we work out the more gradual sunset of other commands within that CLI and answer their stories elsewhere. e.g,:

This command is being deprecated from the `apollo` CLI as it's now covered
by functionality in the new Apollo Rover CLI.  Start migrating today with the
instructions in our migrating guide at https://go.apollo.dev/t/rover-migration.

(With that being a shortlink setup on the /t/ "tooling" namespace to match other apollo CLI output at go.apollo.dev)

[JakeDawkins]

I like this! I think we could also be a little more specific about the command usage recommended in the first comment

I think we could use the --service-name flag to determine if people are trying to run checks/pushed on a federated endpoint and message appropriately.

We could maybe even consider adding a message in apollo client:download-schema since that functionality is completely replaced in rover graph fetch, but that may be a bigger convo about whether we want to suggest people use rover for client: stuff

[abernix]

Just to copy some of the possible requirements (these haven't been agreed upon yet, per se, though we might just sort them out here) from a doc we had drafted at one point:

• The Apollo CLI should have deprecation warnings where applicable, added in a patch update
  • Deprecation warning message printed at runtime for any service: commands, pointing to rover start page
  • Deprecation warning in command docs (these are generated from code)
  • Deprecation warning at the top of the Readme that will be visible in the repo and on NPM
  • JSON and machine-readable formats should not be affected in any way

[EverlastingBugstopper]

this all looks good to me - eventually once we find a home for the client code we will likely want to make use of the npm deprecate command as well, though that can be tracked separately from this work I believe.

[hwillson]

This all looks great - thanks all!

@EverlastingBugstopper deprecating the client stuff is going to take longer, but we're working on a plan for it (and the day we're able to run npm deprecate for apollo is the day you'll find me drowning in tears of joy 😂).

[lrlna]

What is the best way for us to make sure apollo gets this messaging in to its current version in the next week or two?

[hwillson]

👋 @lrlna - I'm working on these changes now. They should be live by this Friday (2021-05-07). Thanks!

[lrlna]

@hwillson amazing, thank you! 🙌