Create --variant flag, deprecate --tag flag (#1849)

* Make newlines (optional commit)

* Change references of Apollo Engine in flags

These default flags were still referencing Apollo Engine instead of
Graph Manager (even though some were hidden). Additionally, this updates
the docs to be more accurate. Happy to take this commit into another PR
if you'd like!

* Support variant flag in service:list command

This change supports the variant flag (with character -v) in addition to
the "tag" flag, which allows us to start using the new terminology. The
'--tag' flag is still supported, and there is verification that the two
sibling flags cannot be used together.

* Give deprecation warning to --tag users

* Rename errors util to sharedMessages

* Move tag flag deprecation warning to sharedMessages

* Support the variant flag in service:check

Also remove an unused variable in service:list

* Update service:delete to use variant flag

Also update description of the flags

* Add support to service:download to use --variant

Also simplify an import in apollo-language-server
Also add a XXX comment to service:download to illustrate a problem

* Change magical config tag to use variant

Additionally, this updates the text output in the service:check command
to consistently use graph@variant everywhere

* Rename magical config.tag to config.variant

This is a find and replace all, and I verified every command still works
after this (both with --tag and --variant). Will post screenshots of how
everything looks in the PR :)

* Update snapshots

A previous commit added `@variant` everywhere, and these snapshot
updates should be ONLY that.

* Put all handling into the magical config.variant

* Replace all flags.tag references to config.variant

* Add variant to the client: commands

All of the client commands share common flags, so no further changes are
required. Also, all of them use config.variant, so yay! :)

* Warn about deprecation at magical config.variant

Remove the deprecation warning from specific callsites and rely on the
deprecation warning appearing when the config.variant value is set

* Support for service:push variant

Also, this changes the default value of the flag, but it does NOT change
the behaviour, since `config.variant` always defaults to "current" if
flags and configuration are not set. The reason this was done is because
flags.tag will be non-null if there is a default, which causes the
deprecation message to always print

* Changes word "tag" in some user-facing messages

* Some small tweaks in wording

Mainly renaming service to graph and "schema" to service, which felt a
little meh, but more in line with the name of the command

* Update changelog

* Updates snapshots to match new messaging

This should only include changes to some minor message changes in
service:check

Co-authored-by: Adam Zionts <adam@meteor.com>

Author: zionts

CHANGELOG.md

@@ -3,7 +3,14 @@
 ## Upcoming
 
 - `apollo`
-  - <First `apollo` related entry goes here>
+  - https://github.com/apollographql/apollo-tooling/pull/1849
+    - Update all commands that supported --tag to prefer --variant and indicate a deprecation warning for --tag
+        - All usages of --tag will continue to work
+        - The two flags cannot be used in tandem (i.e. --variant replaces --tag)
+        - --tag will no longer appear in help messages
+    - Updates of --help messages
+    - Bug fix of some apollo commands that did not work with `graph@variant` parsing within the apollo.config.js
+    - Improved error messaging when a graph is not specified in either `apollo.config.js` or within the API key.
 - `apollo-codegen-flow`
   - <First `apollo-codegen-flow` related entry goes here>
 - `apollo-codegen-scala`

packages/apollo-language-server/src/config/__tests__/config.ts

@@ -55,21 +55,21 @@ describe("ApolloConfig", () => {
     });
   });
 
-  describe("tag", () => {
-    it("gets default tag when none is set", () => {
+  describe("variant", () => {
+    it("gets default variant when none is set", () => {
       const config = new ApolloConfig({ client: { service: "hai" } });
-      expect(config.tag).toEqual("current");
+      expect(config.variant).toEqual("current");
     });
 
-    it("gets tag from service specifier", () => {
+    it("gets variant from service specifier", () => {
       const config = new ApolloConfig({ client: { service: "hai@master" } });
-      expect(config.tag).toEqual("master");
+      expect(config.variant).toEqual("master");
     });
 
-    it("can set and override tags", () => {
+    it("can set and override variants", () => {
       const config = new ApolloConfig({ client: { service: "hai@master" } });
-      config.tag = "new";
-      expect(config.tag).toEqual("new");
+      config.variant = "new";
+      expect(config.variant).toEqual("new");
     });
   });
 

packages/apollo-language-server/src/config/config.ts

@@ -135,7 +135,7 @@ export class ApolloConfig {
   public name?: string;
   public service?: ServiceConfigFormat;
   public client?: ClientConfigFormat;
-  private _tag?: string;
+  private _variant?: string;
 
   constructor(public rawConfig: ApolloConfigFormat, public configURI?: URI) {
     this.isService = !!rawConfig.service;
@@ -162,12 +162,12 @@ export class ApolloConfig {
     return configs;
   }
 
-  set tag(tag: string) {
-    this._tag = tag;
+  set variant(tag: string) {
+    this._variant = tag;
   }
 
-  get tag(): string {
-    if (this._tag) return this._tag;
+  get variant(): string {
+    if (this._variant) return this._variant;
     let tag: string = "current";
     if (this.client && typeof this.client.service === "string") {
       const specifierTag = parseServiceSpecifier(this.client

packages/apollo-language-server/src/project/client.ts

@@ -177,7 +177,7 @@ export class GraphQLClientProject extends GraphQLProject {
         client: totalTypes - serviceTypes,
         total: totalTypes
       },
-      tag: this.config.tag,
+      tag: this.config.variant,
       loaded: Boolean(this.schema || this.serviceSchema),
       lastFetch: this.lastLoadDate
     };
@@ -202,7 +202,7 @@ export class GraphQLClientProject extends GraphQLProject {
       (async () => {
         this.serviceSchema = augmentSchemaWithGeneratedSDLIfNeeded(
           await this.schemaProvider.resolveSchema({
-            tag: tag || this.config.tag,
+            tag: tag || this.config.variant,
             force: true
           })
         );

packages/apollo-language-server/src/providers/schema/engine.ts

@@ -4,7 +4,7 @@ import gql from "graphql-tag";
 import { GraphQLSchema, buildClientSchema } from "graphql";
 import { ApolloEngineClient, ClientIdentity } from "../../engine";
 import { ClientConfig, parseServiceSpecifier } from "../../config";
-import { getServiceFromKey, isServiceKey } from "../../config/utils";
+import { getServiceFromKey, isServiceKey } from "../../config";
 import {
   GraphQLSchemaProvider,
   SchemaChangeUnsubscribeHandler,

packages/apollo/src/Command.ts

@@ -17,6 +17,7 @@ import {
 import { WithRequired, DeepPartial } from "apollo-env";
 import { OclifLoadingHandler } from "./OclifLoadingHandler";
 import URI from "vscode-uri";
+import { tagFlagDeprecatedWarning } from "./utils/sharedMessages";
 
 const { version, referenceID } = require("../package.json");
 
@@ -36,6 +37,7 @@ export interface Flags {
   engine?: string;
   frontend?: string;
   tag?: string;
+  variant?: string;
   skipSSLValidation?: boolean;
 }
 
@@ -76,18 +78,19 @@ export abstract class ProjectCommand extends Command {
         "Additional header to send to server for introspectionQuery. May be used multiple times to add multiple headers. NOTE: The `--endpoint` flag is REQUIRED if using the `--header` flag."
     }),
     endpoint: flags.string({
-      description: "The url of your service"
+      description: "The URL for the CLI use to introspect your service"
     }),
     key: flags.string({
-      description: "The API key for the Apollo Engine service",
+      description:
+        "The API key to use for authentication to Apollo Graph Manager",
       default: () => process.env.ENGINE_API_KEY
     }),
     engine: flags.string({
-      description: "Reporting URL for a custom Apollo Engine deployment",
+      description: "URL for a custom Apollo Graph Manager deployment",
       hidden: true
     }),
     frontend: flags.string({
-      description: "URL for a custom Apollo Engine frontend",
+      description: "URL for a custom Apollo Graph Manager frontend",
       hidden: true
     })
   };
@@ -143,7 +146,10 @@ export abstract class ProjectCommand extends Command {
       return;
     }
 
-    config.tag = flags.tag || config.tag || "current";
+    config.variant = flags.variant || flags.tag || config.variant;
+    if (flags.tag) {
+      console.warn(tagFlagDeprecatedWarning);
+    }
     //  flag overrides
     config.setDefaults({
       engine: {
@@ -281,7 +287,16 @@ export abstract class ClientCommand extends ProjectCommand {
     }),
     tag: flags.string({
       char: "t",
-      description: "The published service tag for this client"
+      description:
+        "[Deprecated: please use --variant instead] The tag (AKA variant) of the graph in Apollo Graph Manager to associate this client to",
+      hidden: true,
+      exclusive: ["variant"]
+    }),
+    variant: flags.string({
+      char: "v",
+      description:
+        "The variant of the graph in Apollo Graph Manager to associate this client to",
+      exclusive: ["tag"]
     }),
     queries: flags.string({
       description: "Deprecated in favor of the includes flag"

packages/apollo/src/commands/client/check.ts

@@ -8,7 +8,7 @@ import { relative } from "path";
 import { graphqlTypes } from "apollo-language-server";
 import chalk from "chalk";
 import envCi from "env-ci";
-import { graphUndefinedError } from "../../utils/errors";
+import { graphUndefinedError } from "../../utils/sharedMessages";
 
 const { ValidationErrorType } = graphqlTypes;
 type ValidationResult = graphqlTypes.ValidateOperations_service_validateOperations_validationResults;
@@ -60,7 +60,7 @@ export default class ClientCheck extends ClientCommand {
 
             ctx.validationResults = await project.engine.validateOperations({
               id: config.name,
-              tag: config.tag,
+              tag: config.variant,
               operations: ctx.operations.map(({ body, name }) => ({
                 body,
                 name

packages/apollo/src/commands/client/codegen.ts

@@ -132,7 +132,7 @@ export default class Generate extends ClientCommand {
 
     let write;
     const run = () =>
-      this.runTasks(({ flags, args, project }) => {
+      this.runTasks(({ flags, args, project, config }) => {
         let inferredTarget: TargetType = "" as TargetType;
         if (
           ["json", "swift", "typescript", "flow", "scala"].includes(
@@ -172,7 +172,7 @@ export default class Generate extends ClientCommand {
             task: async (ctx, task) => {
               task.title = `Generating query files with '${inferredTarget}' target`;
               const schema = await project.resolveSchema({
-                tag: flags.tag
+                tag: config.variant
               });
 
               if (!schema) throw new Error("Error loading schema");

packages/apollo/src/commands/client/download-schema.ts

@@ -23,14 +23,14 @@ export default class SchemaDownload extends ClientCommand {
   ];
 
   async run() {
-    await this.runTasks(({ args, project, flags }) => {
+    await this.runTasks(({ args, project, flags, config }) => {
       const extension = args.output.split(".").pop();
       const isSDLFormat = ["graphql", "graphqls", "gql"].includes(extension);
       return [
         {
           title: `Saving schema to ${args.output}`,
           task: async () => {
-            const schema = await project.resolveSchema({ tag: flags.tag });
+            const schema = await project.resolveSchema({ tag: config.variant });
             const formattedSchema = isSDLFormat
               ? printSchema(schema)
               : JSON.stringify(introspectionFromSchema(schema), null, 2);

packages/apollo/src/commands/client/push.ts

@@ -14,7 +14,7 @@ import {
   ApolloConfig,
   graphqlTypes
 } from "apollo-language-server";
-import { graphUndefinedError } from "../../utils/errors";
+import { graphUndefinedError } from "../../utils/sharedMessages";
 
 export default class ClientPush extends ClientCommand {
   static description =
@@ -53,7 +53,7 @@ export default class ClientPush extends ClientCommand {
           },
           {
             title: `Checked operations against ${chalk.cyan(
-              config.name + "@" + config.tag
+              config.name + "@" + config.variant
             )}`,
             task: async () => {}
           },
@@ -87,7 +87,7 @@ export default class ClientPush extends ClientCommand {
                 id: config.name,
                 operations: operationManifest,
                 manifestVersion: 2,
-                graphVariant: config.tag
+                graphVariant: config.variant
               };
               const { operations: _op, ...restVariables } = variables;
               this.debug("Variables sent to Apollo");