Merge pull request #1 from davidmorgan/setup

Create package:pedantic.

CHANGELOG.md

@@ -1,3 +1,5 @@
 ## 1.0.0
 
-* Initial version.
+- Describe Dart static analysis use at Google in `README.md`.
+- Add sample `analysis_options.yaml`.
+- Add `unawaited` method for silencing the `unawaited_futures` lint.

README.md

@@ -1,9 +1,72 @@
-# sample
+# pedantic
 
-A library for Dart developers. It is awesome.
+This package serves three purposes:
+
+ - It documents how Dart static analysis is used internally at Google,
+   including best practices for the code we write. The documentation is
+   this `README.md`.
+ - It contains a corresponding sample `analysis_options.yaml`.
+ - It contains occasional small snippets of Dart code that are used in
+   implementing those best practices.
+
+Note that everything here fits within the guidelines set out in
+[Effective Dart](https://www.dartlang.org/guides/language/effective-dart).
+You could think of that document as the _design_ and this package as one
+possible partial _implementation_.
+
+## Using Static Analysis
+
+Here is how static analysis is used internally at Google:
+
+ - By default we disallow checking in code with any errors, warnings, or hints.
+   - The `TODO` hint is a permanent exception.
+   - Deprecation hints are a permanent exception. Deprecations are handled
+     separately on a case by case basis.
+   - `unnecessary_no_such_method`, `unused_element`, `unused_field` and
+     `unused_local_variable` are allowed.
+   - When a new SDK version adds new errors, warnings or hints, we either clean
+     up everything before switching SDK version or maintain a whitelist of
+     allowed violations so it can be gradually cleaned up.
+ - Lints are considered and enabled on a case by case basis. When enabling a
+   lint we first clean up all pre-existing violations. After it's enabled, any
+   attempt to check in a further violation will be blocked.
+
+## Enabled Lints
+
+The currently enabled lints can be found in the sample
+[analysis_options.yaml](https://github.com/dart-lang/pedantic/blob/master/analysis_options.yaml).
+
+## Unused Lints
+
+The following lints have been considered and will _not_ be enforced:
+
+`always_put_control_body_on_new_line`
+violates Effective Dart "DO format your code using dartfmt". See note about 
+Flutter SDK style below.
+
+`always_specify_types`
+violates Effective Dart "AVOID type annotating initialized local variables"
+and others. See note about Flutter SDK style below.
+
+`avoid_as`
+does not reflect standard usage. See note about Flutter SDK style below.
+
+`empty_statements`
+is superfluous, enforcing use of `dartfmt` is sufficient to make empty
+ statements obvious.
+
+`prefer_bool_in_asserts`
+ is obsolete in Dart 2; bool is required in asserts.
+
+`prefer_final_locals`
+does not reflect standard usage.
+
+Note on Flutter SDK Style: some lints were created specifically to support
+Flutter SDK development. Flutter app developers should instead use standard
+Dart style as described in Effective Dart, and should not use these lints.
 
 ## Features and bugs
 
 Please file feature requests and bugs at the [issue tracker][tracker].
 
-[tracker]: https://github.com/dart-lang/sample/issues
+[tracker]: https://github.com/dart-lang/pedantic/issues

analysis_options.yaml

@@ -1,2 +1,23 @@
-analyzer:
-  strong-mode: true
+# Copyright (c) 2018, the Dart project authors.  Please see the AUTHORS file
+# for details. All rights reserved. Use of this source code is governed by a
+# BSD-style license that can be found in the LICENSE file.
+#
+# Google internally enforced rules. See README.md for more information,
+# including a list of lints that are intentionally _not_ enforced.
+
+linter:
+  rules:
+    - avoid_empty_else
+    - avoid_relative_lib_imports
+    - avoid_return_types_on_setters
+    - avoid_types_as_parameter_names
+    - control_flow_in_finally
+    - no_duplicate_case_values
+    - prefer_contains
+    - prefer_equal_for_default_values
+    - prefer_is_not_empty
+    - recursive_getters
+    - throw_in_finally
+    - unrelated_type_equality_checks
+    - use_rethrow_when_possible
+    - valid_regexps

lib/pedantic.dart

@@ -0,0 +1,25 @@
+// Copyright (c) 2018, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:async' show Future;
+
+/// Indicates to tools that [future] is intentionally not `await`-ed.
+///
+/// In an `async` context, it is normally expected than all [Future]s are
+/// awaited, and that is the basis of the lint `unawaited_futures`. However,
+/// there are times where one or more futures are intentionally not awaited.
+/// This function may be used to ignore a particular future. It silences the
+/// `unawaited_futures` lint.
+///
+/// ```
+/// Future<void> saveUserPreferences() async {
+///   await _writePreferences();
+///
+///   // While 'log' returns a Future, the consumer of 'saveUserPreferences'
+///   // is unlikely to want to wait for that future to complete; they only
+///   // care about the preferences being written).
+///   unawaited(log('Preferences saved!'));
+/// }
+/// ```
+void unawaited(Future<void> future) {}

pubspec.yaml

@@ -1,15 +1,8 @@
-name: sample
+name: pedantic
 version: 1.0.0-dev
-description: A sample library.
+description: How to get the most value from Dart static analysis.
 author: Dart Team <[email protected]>
-homepage: https://github.com/dart-lang/sample
+homepage: https://github.com/dart-lang/pedantic
 
 environment:
-  sdk: '>=1.24.0 <2.0.0'
-
-dependencies:
-  # lib_name: "^1.2.0"
-
-dev_dependencies:
-  # Narrow this constraint if you use more advanced test features.
-  test: "^0.12.0"
+  sdk: '>=2.0.0 <3.0.0'