Merge pull request #275 from Workiva/v2_prep

AF-2759 V2 Prep: deprecate docs, examples, saucelabs; add dart1-only and dart2-only

Author: rmconsole3-wf

.gitignore

@@ -23,5 +23,6 @@ test_reports/
 /test_fixtures/coverage/functional_test/test/functional/simple_test.dart.temp.html
 /test_fixtures/coverage/non_test_file/coverage/
 /test_fixtures/coverage/vm/coverage/
+/test_fixtures/dart_x_only/doc/api/
 /test_fixtures/docs/docs/doc/api/
 /test_fixtures/format/changes_needed_temp/

README.md

@@ -9,12 +9,6 @@
 
 ---
 
-#### Looking for the 2.0.0 Alpha?
-
-https://github.com/Workiva/dart_dev/blob/2.0.0-alpha/README.md
-
----
-
 - [**Motivation**](#motivation)
 - [**Supported Tasks**](#supported-tasks)
 - [**Getting Started**](#getting-started)
@@ -91,8 +85,8 @@ local tasks.
 - **Coverage:** collects coverage over test suites (unit, integration, and functional) and generates a report. Uses the [`coverage` package](https://github.com/dart-lang/coverage).
 - **Code Formatting:** runs the [`dartfmt` tool from the `dart_style` package](https://github.com/dart-lang/dart_style) over source code.
 - **Static Analysis:** runs the [`dartanalyzer`](https://www.dartlang.org/tools/analyzer/) over source code.
-- **Documentation Generation:** runs the tool from [the `dartdoc` package](https://github.com/dart-lang/dartdoc) to generate docs.
-- **Serving Examples:** uses [`pub serve`](https://www.dartlang.org/tools/pub/cmd/pub-serve.html) to serve the project examples.
+- (DEPRECATED) **Documentation Generation:** runs the tool from [the `dartdoc` package](https://github.com/dart-lang/dartdoc) to generate docs.
+- (DEPRECATED) **Serving Examples:** uses [`pub serve`](https://www.dartlang.org/tools/pub/cmd/pub-serve.html) to serve the project examples.
 - **Applying a License to Source Files:** copies a LICENSE file to all applicable files.
 - **Generate a test runner file:** that allows for faster test execution.
 - **Running dart unit tests on Sauce Labs:** compiles dart unit tests that can be run in the browser and executes them on various platforms using Sauce Labs.
@@ -247,23 +241,23 @@ running any of the following tasks:
 ddev analyze
 ddev copy-license
 ddev coverage
-ddev docs
-ddev examples
+ddev docs  # (DEPRECATED)
+ddev examples  # (DEPRECATED)
 ddev format
 ddev gen-test-runner
-ddev saucelabs
+ddev saucelabs  # (DEPRECATED)
 ddev task-runner
 ddev test
 
 # without the alias
 pub run dart_dev analyze
 pub run dart_dev copy-license
 pub run dart_dev coverage
-pub run dart_dev docs
-pub run dart_dev examples
+pub run dart_dev docs  # (DEPRECATED)
+pub run dart_dev examples   # (DEPRECATED)
 pub run dart_dev format
 pub run dart_dev gen-test-runner
-pub run dart_dev saucelabs
+pub run dart_dev saucelabs  # (DEPRECATED)
 pub run dart_dev task-runner
 pub run dart_dev test
 ```
@@ -272,6 +266,33 @@ Add the `-h` flag to any of the above commands to receive additional help
 information specific to that task.
 
 
+#### Convenience Tasks for Targeting Dart1 and/or Dart2
+
+To help with the transition from Dart1 to Dart2, you can leverage the `dart1-only`
+and `dart2-only` tasks to conditionally run another dart_dev task or any executable.
+
+```bash
+# Run a dart_dev task only on Dart1:
+$ ddev dart1-only test
+
+# Run a dart_dev task with additional args only on Dart1:
+$ ddev dart1-only -- format --check
+
+# Run an shell script only on Dart1:
+$ ddev dart1-only ./example.sh
+
+# Run an executable with additional args only on Dart1:
+$ ddev dart1-only -- pub serve web --port 8080
+
+# The `dart2-only` task works exactly the same, but only runs on Dart2:
+$ ddev dart2-only test
+$ ddev dart2-only -- format --check
+$ ddev dart2-only ./example.sh
+$ ddev dart2-only -- pub run build_runner serve web:8080
+```
+
+
+
 ## Project Configuration
 Project configuration occurs in the `tool/dev.dart` file where the `config`
 instance is imported from the `dart_dev` package. The bare minimum for this file

lib/api.dart

@@ -16,7 +16,11 @@ library dart_dev.api;
 
 export 'package:dart_dev/src/tasks/analyze/api.dart' show AnalyzeTask, analyze;
 export 'package:dart_dev/src/tasks/examples/api.dart'
-    show ExamplesTask, serveExamples;
+    show
+        // ignore: deprecated_member_use
+        ExamplesTask,
+        // ignore: deprecated_member_use
+        serveExamples;
 export 'package:dart_dev/src/tasks/format/api.dart'
     show FilesToFormat, FormatTask, format, getFilesToFormat;
 export 'package:dart_dev/src/tasks/init/api.dart' show InitTask, init;

lib/src/dart_dev_cli.dart

@@ -27,6 +27,7 @@ import 'package:dart_dev/src/tasks/analyze/cli.dart';
 import 'package:dart_dev/src/tasks/bash_completion/cli.dart';
 import 'package:dart_dev/src/tasks/copy_license/cli.dart';
 import 'package:dart_dev/src/tasks/coverage/cli.dart';
+import 'package:dart_dev/src/tasks/dart_x_only/cli.dart';
 import 'package:dart_dev/src/tasks/docs/cli.dart';
 import 'package:dart_dev/src/tasks/examples/cli.dart';
 import 'package:dart_dev/src/tasks/export_config/cli.dart';
@@ -59,12 +60,15 @@ dev(List<String> args) async {
   registerTask(new BashCompletionCli(), config.bashCompletion);
   registerTask(new CopyLicenseCli(), config.copyLicense);
   registerTask(new CoverageCli(), config.coverage);
+  // ignore: deprecated_member_use
   registerTask(new DocsCli(), config.docs);
+  // ignore: deprecated_member_use
   registerTask(new ExamplesCli(), config.examples);
   registerTask(new ExportConfigCli(), new TaskConfig());
   registerTask(new FormatCli(), config.format);
   registerTask(new GenTestRunnerCli(), config.genTestRunner);
   registerTask(new InitCli(), config.init);
+  // ignore: deprecated_member_use
   registerTask(new SauceRunnerCli(), config.saucelabs);
   registerTask(new TaskRunnerCli(), config.taskRunner);
   registerTask(new TestCli(), config.test);
@@ -80,6 +84,12 @@ dev(List<String> args) async {
     exit(exitCode);
   }
 
+  // Register these tasks after the rest of the tasks have been registered
+  // because they depend on the list of other available dart_dev tasks.
+  final availableTasks = _cliTasks.keys.toSet();
+  registerTask(new Dart1OnlyCli(availableTasks), config.dart1Only);
+  registerTask(new Dart2OnlyCli(availableTasks), config.dart2Only);
+
   await _run(args);
   exit(exitCode);
 }

lib/src/tasks/config.dart

@@ -18,6 +18,7 @@ import 'package:dart_dev/src/tasks/analyze/config.dart';
 import 'package:dart_dev/src/tasks/bash_completion/config.dart';
 import 'package:dart_dev/src/tasks/copy_license/config.dart';
 import 'package:dart_dev/src/tasks/coverage/config.dart';
+import 'package:dart_dev/src/tasks/dart_x_only/config.dart';
 import 'package:dart_dev/src/tasks/docs/config.dart';
 import 'package:dart_dev/src/tasks/examples/config.dart';
 import 'package:dart_dev/src/tasks/format/config.dart';
@@ -35,13 +36,32 @@ class Config {
   BashCompletionConfig bashCompletion = new BashCompletionConfig();
   CopyLicenseConfig copyLicense = new CopyLicenseConfig();
   CoverageConfig coverage = new CoverageConfig();
+  Dart1OnlyConfig dart1Only = new Dart1OnlyConfig();
+  Dart2OnlyConfig dart2Only = new Dart2OnlyConfig();
+
+  /// Deprecated: 1.10.0
+  /// To be removed: 2.0.0
+  /// Use the `dartdoc` executable instead.
+  @deprecated
   DocsConfig docs = new DocsConfig();
+
+  /// Deprecated 1.10.0
+  /// To be removed: 2.0.0
+  /// Use `pub serve example` or `pub run build_runner serve example:8080`
+  /// instead.
+  @deprecated
   ExamplesConfig examples = new ExamplesConfig();
+
   LocalConfig local = new LocalConfig();
   FormatConfig format = new FormatConfig();
   GenTestRunnerConfig genTestRunner = new GenTestRunnerConfig();
   InitConfig init = new InitConfig();
+
+  /// Deprecated 1.10.0
+  /// To be removed: 2.0.0
+  @deprecated
   SaucelabsConfig saucelabs = new SaucelabsConfig();
+
   TaskRunnerConfig taskRunner = new TaskRunnerConfig();
   TestConfig test = new TestConfig();
 
@@ -50,12 +70,15 @@ class Config {
         'bashCompletion': bashCompletion,
         'copyLicense': copyLicense,
         'coverage': coverage,
+        // ignore: deprecated_member_use
         'docs': docs,
+        // ignore: deprecated_member_use
         'examples': examples,
         'local': local,
         'format': format,
         'genTestRunner': genTestRunner,
         'init': init,
+        // ignore: deprecated_member_use
         'saucelabs': saucelabs,
         'taskRunner': taskRunner,
         'test': test,

lib/src/tasks/dart_x_only/cli.dart

@@ -0,0 +1,91 @@
+// Copyright 2015 Workiva Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+library dart_dev.src.tasks.dart1_only.cli;
+
+import 'dart:async';
+
+import 'package:args/args.dart';
+
+import 'package:dart_dev/util.dart' show TaskProcess, reporter;
+
+import 'package:dart_dev/src/tasks/cli.dart';
+import 'package:dart_dev/src/util.dart';
+
+class Dart1OnlyCli extends DartXOnlyCli {
+  @override
+  final String command = 'dart1-only';
+
+  Dart1OnlyCli(Iterable<String> availableTasks) : super(availableTasks);
+
+  @override
+  bool get shouldRun => dartMajorVersion == 1;
+}
+
+class Dart2OnlyCli extends DartXOnlyCli {
+  @override
+  final String command = 'dart2-only';
+
+  Dart2OnlyCli(Iterable<String> availableTasks) : super(availableTasks);
+
+  @override
+  bool get shouldRun => dartMajorVersion == 2;
+}
+
+abstract class DartXOnlyCli extends TaskCli {
+  @override
+  final ArgParser argParser = new ArgParser();
+
+  final Iterable<String> _availableTasks;
+
+  bool get shouldRun;
+
+  @override
+  String get usage => '${super.usage} <task or executable> [args]';
+
+  DartXOnlyCli(Iterable<String> availableTasks)
+      : _availableTasks = availableTasks;
+
+  @override
+  Future<CliResult> run(ArgResults parsedArgs, {bool color: true}) async {
+    if (parsedArgs.rest.isEmpty) {
+      return new CliResult.fail('A task or executable is required.');
+    }
+
+    if (!shouldRun) {
+      return new CliResult.success('Skipped (Dart $dartMajorVersion)');
+    }
+
+    final target = parsedArgs.rest.first;
+    final targetArgs = parsedArgs.rest.sublist(1);
+
+    String executable;
+    List<String> args;
+    if (_availableTasks.contains(target)) {
+      executable = 'pub';
+      args = <String>['run', 'dart_dev', target]..addAll(targetArgs);
+    } else {
+      executable = target;
+      args = targetArgs;
+    }
+
+    final process = new TaskProcess(executable, args);
+    reporter.logGroup('$executable ${args.join(' ')}',
+        outputStream: process.stdout, errorStream: process.stderr);
+    await process.done;
+    return await process.exitCode == 0
+        ? new CliResult.success()
+        : new CliResult.fail();
+  }
+}

lib/src/tasks/dart_x_only/config.dart

@@ -0,0 +1,21 @@
+// Copyright 2015 Workiva Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+library dart_dev.src.tasks.dart_x_only.config;
+
+import 'package:dart_dev/src/tasks/config.dart';
+
+class Dart1OnlyConfig extends TaskConfig {}
+
+class Dart2OnlyConfig extends TaskConfig {}

lib/src/tasks/docs/cli.dart

@@ -35,6 +35,12 @@ class DocsCli extends TaskCli {
 
   @override
   Future<CliResult> run(ArgResults parsedArgs, {bool color: true}) async {
+    reporter.warning('''
+---- DEPRECATION NOTICE ----
+The docs task is deprecated and will be removed in dart_dev v2.0.0.
+Use `dartdoc` instead.
+----------------------------''');
+
     if (!hasImmediateDependency('dartdoc'))
       return new CliResult.fail(
           'Package "dartdoc" must be an immediate dependency in order to run its executables.');

lib/src/tasks/examples/api.dart

@@ -27,6 +27,11 @@ bool hasExamples() {
   return exampleDir.existsSync();
 }
 
+/// Deprecated 1.10.0
+/// To be removed: 2.0.0
+/// Use `pub serve example` or `pub run build_runner serve example:8080`
+/// instead.
+@deprecated
 ExamplesTask serveExamples(
     {String hostname: defaultHostname, int port: defaultPort}) {
   if (!hasExamples())
@@ -64,6 +69,10 @@ ExamplesTask serveExamples(
   return task;
 }
 
+/// Deprecated: 1.10.0
+/// To be removed: 2.0.0
+/// Use the `dartdoc` executable instead.
+@deprecated
 class ExamplesTask extends Task {
   @override
   final Future<Null> done;

lib/src/tasks/examples/cli.dart

@@ -39,8 +39,16 @@ class ExamplesCli extends TaskCli {
 
   @override
   Future<CliResult> run(ArgResults parsedArgs, {bool color: true}) async {
+    reporter.warning('''
+---- DEPRECATION NOTICE ----
+The examples task is deprecated and will be removed in dart_dev v2.0.0.
+Run `pub serve example` or `pub run build_runner serve example:8080` instead.
+----------------------------''');
+
     String hostname =
+        // ignore: deprecated_member_use
         TaskCli.valueOf('hostname', parsedArgs, config.examples.hostname);
+    // ignore: deprecated_member_use
     var port = TaskCli.valueOf('port', parsedArgs, config.examples.port);
     if (port is String) {
       port = int.parse(port);
@@ -49,6 +57,7 @@ class ExamplesCli extends TaskCli {
     if (!hasExamples())
       return new CliResult.fail('This project does not have any examples.');
 
+    // ignore: deprecated_member_use
     ExamplesTask task = serveExamples(hostname: hostname, port: port);
     reporter.logGroup(task.pubServeCommand,
         outputStream: task.pubServeStdOut, errorStream: task.pubServeStdErr);