template strategy & usage strategy need more definition

🐞 bug report

Affected Package

@angular/core

Is this a regression?

no

Description

Upon using ng update to move to 8.0.0-rc.2 (or later), I get the following prompt:

------ Static Query migration ------
            In preparation for Ivy, developers can now explicitly specify the
            timing of their queries. Read more about this here:
            https://github.com/angular/angular/pull/28810
            
            There are two available migration strategies that can be selected:
              • Template strategy  -  migration tool (short-term gains, rare corrections)
              • Usage strategy  -  best practices (long-term gains, manual corrections)
            For an easy migration, the template strategy is recommended. The usage
            strategy can be used for best practices and a code base that will be more
            flexible to changes going forward.
? What migration strategy do you want to use?

This prompt doesn’t include enough information for me to decide, and the linked PR doesn’t talk about these strategies. It’s unclear what the differences are or what changes will be made.

🌍 Your Environment

Angular Version:

Angular CLI: 8.0.0-rc.2
Node: 12.1.0
OS: linux x64
Angular: 8.0.0-rc.2
... animations, cli, common, compiler, compiler-cli, core, forms
... platform-browser, platform-browser-dynamic, router
... service-worker

Package                           Version
-----------------------------------------------------------
@angular-devkit/architect         0.800.0-rc.2
@angular-devkit/build-angular     0.800.0-rc.2
@angular-devkit/build-optimizer   0.800.0-rc.2
@angular-devkit/build-webpack     0.800.0-rc.2
@angular-devkit/core              8.0.0-rc.2
@angular-devkit/schematics        8.0.0-rc.2
@angular/cdk                      8.0.0-rc.0
@angular/material                 8.0.0-rc.0
@ngtools/webpack                  8.0.0-rc.2
@schematics/angular               8.0.0-rc.2
@schematics/update                0.800.0-rc.2
rxjs                              6.5.1
typescript                        3.4.5
webpack                           4.30.0

[kara]

Agree, we need to expand the messaging.

Note that we should only be prompting if users have ViewChild/ContentChild queries.

[devversion]

The documentation should have code examples for the two strategies.

👍 Examples are definitely a good idea.

Should this be marked as a release blocker?

I’d say so. We want to make the upgrade as easy as possible… and a confusing prompt with not much context doesn’t help with that 😄