[sync] 2021/02/11

.travis.yml

@@ -33,10 +33,8 @@ matrix:
       dart: stable
     - env: TASK="./tool/analyze-and-test-examples.sh --null-safety"
       dart: beta
-#     - env: TASK="./tool/check-code.sh --null-safety"
-#       dart: stable
-#     - env: TASK="./tool/check-code.sh --null-safety"
-#       dart: beta
+    - env: TASK="./tool/analyze-and-test-examples.sh --null-safety"
+      dart: dev
 
 before_install:
   - source ./tool/env-set.sh

CONTRIBUTING.md

@@ -27,24 +27,30 @@ More info:
 
 * To avoid wasting your time, talk with us before you make any nontrivial
   pull request. The [issue tracker][] is a good way to track your progress
-  publicly, but we can also communicate other ways such as email and
-  [Gitter][].
+  publicly, but we also use the #hackers-devrel channel
+  [on Flutter's Discord server][].
 * We use the usual [GitHub pull request][] process.
-* We follow the [Google Developer Documentation Style Guide][].
+* We follow the [Google Developer Documentation Style Guide][],
+  with some additional conventions that we try to document
+  [in the site-shared repo][].
+  In particular, we use [semantic line breaks][].
 * For more ways to contribute to Dart, see the
   [dart-lang/sdk Contributing page][].
 
 [beginner]: https://github.com/dart-lang/site-www/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3A%22help%20wanted%22%20label%3Abeginner%20
 [dart-lang/sdk Contributing page]: https://github.com/dart-lang/sdk/wiki/Contributing
 [GitHub pull request]: https://help.github.com/articles/about-pull-requests/
-[Gitter]: https://gitter.im/dart-lang/home
 [Google Developer Documentation Style Guide]: https://developers.google.com/style/
 [help wanted]: https://github.com/dart-lang/site-www/issues?utf8=%E2%9C%93&q=is%3Aopen%20is%3Aissue%20label%3A%22help%20wanted%22%20
+[in the site-shared repo]: https://github.com/dart-lang/site-shared/blob/master/doc
 [issue tracker]: https://github.com/dart-lang/site-www/issues
+[on Flutter's Discord server]: https://github.com/flutter/flutter/wiki/Chat
 [Report issues]: https://github.com/dart-lang/site-www/issues/new
+[semantic line breaks]: https://github.com/dart-lang/site-shared/blob/master/doc/writing-for-dart-and-flutter-websites.md#semantic-line-breaks
 [sign the CLA]: https://developers.google.com/open-source/cla/individual
 [www]: https://dart.dev
 
+
 ## Updating code samples
 
 If your PR changes Dart code within a page, you'll probably need to change the code in two places:

examples/misc/lib/language_tour/classes/immutable_point.dart

@@ -1,7 +1,6 @@
 // ignore_for_file: sort_constructors_first
 class ImmutablePoint {
-  static final ImmutablePoint origin =
-      const ImmutablePoint(0, 0);
+  static const ImmutablePoint origin = ImmutablePoint(0, 0);
 
   final double x, y;
 

examples/misc/lib/language_tour/variables.dart

@@ -57,7 +57,6 @@ void miscDeclAnalyzedButNotTested() {
 
   {
     // #docregion const-dart-25
-    // Valid compile-time constants as of Dart 2.5.
     const Object i = 3; // Where i is a const Object with an int value...
     const list = [i as int]; // Use a typecast.
     const map = {if (i is int) i: "int"}; // Use is and collection if.

examples/misc/lib/samples/spacecraft.dart

@@ -39,7 +39,7 @@ class Orbiter extends Spacecraft {
 // #enddocregion extends
 
 // #docregion mixin
-class Piloted {
+mixin Piloted {
   int astronauts = 1;
   void describeCrew() {
     print('Number of astronauts: $astronauts');

firebase.json

@@ -129,6 +129,7 @@
 
       { "source": "/go/analysis-server-protocol", "destination": "https://htmlpreview.github.io/?https://github.com/dart-lang/sdk/blob/master/pkg/analysis_server/doc/api.html", "type": 301 },
       { "source": "/go/flutter-upper-bound-deprecation", "destination": "https://github.com/flutter/flutter/issues/68143", "type": 301 },
+      { "source": "/go/dot-packages-deprecation", "destination": "https://github.com/dart-lang/language/blob/master/accepted/future-releases/language-versioning/package-config-file-v2.md", "type": 301 },
       { "source": "/go/dart-fix", "destination": "https://github.com/dart-lang/sdk/blob/master/pkg/dartdev/doc/dart-fix.md", "type": 301 },
       { "source": "/go/experiments", "destination": "/tools/experiment-flags", "type": 301 },
       { "source": "/go/null-safety-migration", "destination": "/null-safety/migration-guide", "type": 301 },

null_safety_examples/analysis_options.yaml

@@ -0,0 +1,39 @@
+include: package:pedantic/analysis_options.1.8.0.yaml
+
+analyzer:
+  exclude: [build/**]
+  strong-mode:
+    implicit-casts: false
+
+linter:
+  # Rules and documentation: http://dart-lang.github.io/linter/lints
+  rules:
+    - annotate_overrides
+    - await_only_futures
+    - camel_case_types
+    - cancel_subscriptions
+    - close_sinks
+    - comment_references
+    - constant_identifier_names
+    - control_flow_in_finally
+    - empty_statements
+    - hash_and_equals
+    - implementation_imports
+    - iterable_contains_unrelated_type
+    - list_remove_unrelated_type
+    - non_constant_identifier_names
+    - one_member_abstracts
+    - only_throw_errors
+    - overridden_fields
+    - package_api_docs
+    - package_names
+    - package_prefixed_library_names
+    - sort_constructors_first
+    - sort_unnamed_constructors_first
+    - test_types_in_equals
+    - throw_in_finally
+    - type_annotate_public_apis
+    - unnecessary_brace_in_string_interps
+    - unnecessary_const
+    - unnecessary_getters_setters
+    - unnecessary_new

null_safety_examples/async_await/analysis_options.yaml

@@ -0,0 +1 @@
+include: ../analysis_options.yaml

null_safety_examples/async_await/bin/async_example.dart

@@ -0,0 +1,25 @@
+Future<void> printOrderMessage() async {
+  print('Awaiting user order...');
+  // #docregion swap-stmts
+  var order = await fetchUserOrder();
+  // print('Awaiting user order...');
+  // #enddocregion swap-stmts
+  print('Your order is: $order');
+}
+
+Future<String> fetchUserOrder() {
+  // Imagine that this function is more complex and slow.
+  return Future.delayed(Duration(seconds: 4), () => 'Large Latte');
+}
+
+Future<void> main() async {
+  countSeconds(4);
+  await printOrderMessage();
+}
+
+// You can ignore this function - it's here to visualize delay time in this example.
+void countSeconds(int s) {
+  for (var i = 1; i <= s; i++) {
+    Future.delayed(Duration(seconds: i), () => print(i));
+  }
+}

null_safety_examples/async_await/bin/futures_intro.dart

@@ -0,0 +1,19 @@
+// #docregion ''
+Future<void> fetchUserOrder() {
+  // Imagine that this function is fetching user info from another service or database.
+  return Future.delayed(Duration(seconds: 2), () => print('Large Latte'));
+}
+// #enddocregion ''
+
+// #docregion error
+Future<void> fetchUserOrderError() {
+// Imagine that this function is fetching user info but encounters a bug
+  return Future.delayed(Duration(seconds: 2),
+      () => throw Exception('Logout failed: user ID is invalid'));
+}
+// #docregion ''
+
+void main() {
+  fetchUserOrder();
+  print('Fetching user order...');
+}

null_safety_examples/async_await/bin/get_order.dart

@@ -0,0 +1,20 @@
+Future<String> createOrderMessage() async {
+  var order = await fetchUserOrder();
+  return 'Your order is: $order';
+}
+
+Future<String> fetchUserOrder() =>
+    // Imagine that this function is more complex and slow.
+    Future.delayed(
+      Duration(seconds: 2),
+      () => 'Large Latte',
+    );
+
+// #docregion main-sig
+Future<void> main() async {
+  // #enddocregion main-sig
+  print('Fetching user order...');
+  // #docregion print-order
+  print(await createOrderMessage());
+  // #enddocregion print-order
+}

null_safety_examples/async_await/bin/get_order_sync_bad.dart

@@ -0,0 +1,21 @@
+// This example shows how *not* to write asynchronous Dart code.
+
+// #docregion no-warning
+String createOrderMessage() {
+  var order = fetchUserOrder();
+  return 'Your order is: $order';
+}
+
+Future<String> fetchUserOrder() =>
+    // Imagine that this function is more complex and slow.
+    Future.delayed(
+      Duration(seconds: 2),
+      () => 'Large Latte',
+    );
+
+// #docregion main-sig
+void main() {
+  // #enddocregion main-sig
+  print('Fetching user order...');
+  print(createOrderMessage());
+}

null_safety_examples/async_await/bin/try_catch.dart

@@ -0,0 +1,24 @@
+Future<void> printOrderMessage() async {
+  // #docregion try-catch
+  try {
+    var order = await fetchUserOrder();
+    print('Awaiting user order...');
+    print(order);
+  } catch (err) {
+    print('Caught error: $err');
+  }
+  // #enddocregion try-catch
+}
+
+Future<String> fetchUserOrder() {
+  // Imagine that this function is more complex.
+  var str = Future.delayed(
+      Duration(seconds: 4),
+      // ignore: only_throw_errors
+      () => throw 'Cannot locate user order');
+  return str;
+}
+
+Future<void> main() async {
+  await printOrderMessage();
+}

null_safety_examples/async_await/dart_test.yaml

@@ -0,0 +1 @@
+include: ../dart_test_base_browser.yaml

null_safety_examples/async_await/pubspec.yaml

@@ -0,0 +1,10 @@
+name: async_await
+description: dart.dev example code.
+
+environment:
+  sdk: ">=2.12.0-0 <3.0.0"
+
+dev_dependencies:
+  examples_util: {path: ../util}
+  pedantic: ^1.10.0-nullsafety.3
+  test: ^1.16.0-nullsafety.13

null_safety_examples/async_await/test/async_await_test.dart

@@ -0,0 +1,55 @@
+import 'package:test/test.dart';
+import 'package:examples_util/print_matcher.dart' as m;
+
+import '../bin/async_example.dart' as async_example;
+import '../bin/futures_intro.dart' as futures_intro;
+import '../bin/get_order_sync_bad.dart' as get_order_sync_bad;
+import '../bin/get_order.dart' as get_order;
+import '../bin/try_catch.dart' as try_catch;
+
+void main() {
+  test('async_example', () {
+    final output = '''
+      Awaiting user order...
+      1
+      2
+      3
+      4
+      Your order is: Large Latte
+    ''';
+    expect(async_example.main, m.printsLines(output));
+  });
+
+  test('futures_intro', () {
+    final output = '''
+      Fetching user order...
+      Large Latte
+    ''';
+    expect(
+        () => Future.wait([
+              Future.delayed(Duration(seconds: 4)),
+              Future.sync(futures_intro.main),
+            ]),
+        m.printsLines(output));
+  });
+
+  test('get_order_sync_bad', () {
+    final output = '''
+      Fetching user order...
+      Your order is: Instance of 'Future<String>'
+    ''';
+    expect(get_order_sync_bad.main, m.printsLines(output));
+  });
+
+  test('get_order', () {
+    final output = '''
+      Fetching user order...
+      Your order is: Large Latte
+    ''';
+    expect(get_order.main, m.printsLines(output));
+  });
+
+  test('try_catch', () {
+    expect(try_catch.main, m.prints('Caught error: Cannot locate user order'));
+  });
+}

null_safety_examples/dart_test_base.yaml

@@ -0,0 +1,2 @@
+# When analyzing build/test logs, the expanded reporter is better:
+reporter: expanded

null_safety_examples/dart_test_base_browser.yaml

@@ -0,0 +1,13 @@
+include: dart_test_base.yaml
+
+tags:
+  browser:
+
+# Chrome option required because Travis is't running under sudo
+# https://docs.travis-ci.com/user/chrome#Sandboxing
+define_platforms:
+  travischrome:
+    name: Chrome for Travis w/o sudo
+    extends: chrome
+    settings:
+      arguments: --no-sandbox

null_safety_examples/iterables/analysis_options.yaml

@@ -0,0 +1 @@
+include: ../analysis_options.yaml

null_safety_examples/iterables/pubspec.yaml

@@ -0,0 +1,10 @@
+name: iterables
+description: dart.dev example code.
+
+environment:
+  sdk: ">=2.12.0-0 <3.0.0"
+
+dev_dependencies:
+  examples_util: {path: ../util}
+  pedantic: ^1.10.0-nullsafety.3
+  test: ^1.16.0-nullsafety.13