Merge pull request #1 from davidmorgan/setup
Create package:pedantic.
diff --git a/.test_config b/.test_config
deleted file mode 100644
index 352d2fe..0000000
--- a/.test_config
+++ /dev/null
@@ -1,3 +0,0 @@
-{
- "test_package": true
-}
diff --git a/.travis.yml b/.travis.yml
deleted file mode 100644
index 9124e03..0000000
--- a/.travis.yml
+++ /dev/null
@@ -1,33 +0,0 @@
-language: dart
-
-# By default, builds are run in containers.
-# https://docs.travis-ci.com/user/getting-started/#Selecting-infrastructure-(optional)
-# Set `sudo: true` to disable containers if you need to use sudo in your scripts.
-# sudo: true
-
-dart:
-- dev
-- stable
-
-# See https://docs.travis-ci.com/user/languages/dart/ for details.
-dart_task:
-- test: --platform vm
-# Uncomment this line to run tests on the browser.
-# - test: --platform firefox
-
-# Only run one instance of the formatter and the analyzer, rather than running
-# them against each Dart version.
-matrix:
- include:
- - dart: stable
- dart_task: dartfmt
- - dart: dev
- dart_task: dartanalyzer
-
-# Only building master means that we don't run two builds for each pull request.
-branches:
- only: [master]
-
-cache:
- directories:
- - $HOME/.pub-cache
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5b26ad3..bdef44a 100644
--- a/CHANGELOG.md
+++ b/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.
diff --git a/README.md b/README.md
index 289911b..184a8da 100644
--- a/README.md
+++ b/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
diff --git a/analysis_options.yaml b/analysis_options.yaml
index a10d4c5..1844c97 100644
--- a/analysis_options.yaml
+++ b/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
diff --git a/lib/pedantic.dart b/lib/pedantic.dart
new file mode 100644
index 0000000..c48d67b
--- /dev/null
+++ b/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) {}
diff --git a/lib/sample.dart b/lib/sample.dart
deleted file mode 100644
index 5b64738..0000000
--- a/lib/sample.dart
+++ /dev/null
@@ -1,5 +0,0 @@
-// Copyright (c) 2017, 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.
-
-main() => print('foo');
diff --git a/pubspec.yaml b/pubspec.yaml
index 67c7c8e..0d47154 100644
--- a/pubspec.yaml
+++ b/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 <misc@dartlang.org>
-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'
diff --git a/test/all_test.dart b/test/all_test.dart
deleted file mode 100644
index 88561f1..0000000
--- a/test/all_test.dart
+++ /dev/null
@@ -1,12 +0,0 @@
-// Copyright (c) 2017, 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 'package:sample/sample.dart';
-import 'package:test/test.dart';
-
-main() {
- group('A group of tests', () {
- test('First Test', () {});
- });
-}
diff --git a/todo.txt b/todo.txt
deleted file mode 100644
index 8a638e5..0000000
--- a/todo.txt
+++ /dev/null
@@ -1,9 +0,0 @@
-- rename project in pubspec.yaml
-- update description in pubspec.yaml
-- update the homepage: field in pubspec.yaml
-
-- rename project in readme.md
-- update description in readme.md
-- update the [tracker] url in readme.md
-
-- delete todo.txt :)
