Introduce a set of "canonical" lints for Google projects

.analysis_options

@@ -3,47 +3,37 @@ analyzer:
   exclude:
     - test/_data/**
     - test/rules/**
+
+###############################################################################
+# === FROM lib/canonical/google.analysis_options ===
+#
+# See lib/canonical/google.md for the source of these rules and why they were
+# picked out of the all the available lint rules.
+###############################################################################
 linter:
   rules:
-    # - always_declare_return_types
-    # - always_specify_types
-    - annotate_overrides
-    # - avoid_as
+    # Errors
     - avoid_empty_else
-    - avoid_init_to_null
-    - avoid_return_types_on_setters
-    - await_only_futures
-    # - camel_case_types
-    - cancel_subscriptions
-    # - close_sinks # https://github.com/dart-lang/linter/issues/268
     - comment_references
-    # - constant_identifier_names
     - control_flow_in_finally
-    - empty_constructor_bodies
     - empty_statements
     - hash_and_equals
-    # - implementation_imports
-    - iterable_contains_unrelated_type
+    - test_types_in_equals
+    - throw_in_finally
+    - unrelated_type_equality_checks
+    - valid_regexps
+
+    # Style
+    - annotate_overrides
+    - avoid_init_to_null
+    - avoid_return_types_on_setters
+    - await_only_futures
+    - camel_case_types
+    - empty_catches
+    - empty_constructor_bodies
     - library_names
     - library_prefixes
-    # - non_constant_identifier_names
-    # - one_member_abstracts
-    - only_throw_errors
-    - overridden_fields
-    - package_api_docs
-    - package_names
-    - package_prefixed_library_names
+    - non_constant_identifier_names
     - prefer_is_not_empty
-    # - public_member_api_docs
     - slash_for_doc_comments
-    # - sort_constructors_first
-    # - sort_unnamed_constructors_first
-    # - super_goes_last
-    - test_types_in_equals
-    - throw_in_finally
-    # - type_annotate_public_apis
     - type_init_formals
-    - unawaited_futures
-    - unnecessary_brace_in_string_interp
-    - unnecessary_getters_setters
-    - unrelated_type_equality_checks

lib/canonical/google.analysis_options

@@ -0,0 +1,35 @@
+# Strict set of lints that are enforced by the Dart team.
+#
+# New packages in dart-lang/* should **only** use this set of lints and not any
+# additional ones without changing this list - i.e. we need uninformity in our
+# packages.
+#
+# See "google.md" for the decision making progress in maintaining this set.
+
+linter:
+  rules:
+     # Errors
+     - avoid_empty_else
+     - comment_references
+     - control_flow_in_finally
+     - empty_statements
+     - hash_and_equals
+     - test_types_in_equals
+     - throw_in_finally
+     - unrelated_type_equality_checks
+     - valid_regexps
+
+     # Style
+     - annotate_overrides
+     - avoid_init_to_null
+     - avoid_return_types_on_setters
+     - await_only_futures
+     - camel_case_types
+     - empty_catches
+     - empty_constructor_bodies
+     - library_names
+     - library_prefixes
+     - non_constant_identifier_names
+     - prefer_is_not_empty
+     - slash_for_doc_comments
+     - type_init_formals

lib/canonical/google.md

@@ -0,0 +1,34 @@
+As visible in `google.analysis_options`, not all available lint rules are
+suggested for new Google projects.
+
+Instead, a strict *subset* of the rules have been curated based on being:
+
+- Useful: A strongly defined purpose (prevents errors, enforces style)
+- Effective: 0 false positives, does not create extra work for contributors
+- Consistent: Does not conflict with the [style guide][style] or other lints
+
+[style]: https://www.dartlang.org/guides/language/effective-dart/style
+
+Some rules have good intentions, but would be difficult to consistently enforce
+across all Google-owned packages in `https://github.com/dart-lang/*` or would
+conflict with the spirit of the style guide - i.e. treating "consider" or
+"prefer" as "must".
+
+In general, all of the rules in the curated list would be safely enforcable
+with a presubmit script on travis or another continious integration system. It
+is **strongly not recommended** to enable any other lint rules in Dart-owned
+packages.
+
+## What about Angular or Flutter?
+
+Some frameworks may introduce additional lints _on top of_ this list (i.e. they
+do not contradict with any other rules, and would conditionally apply on
+certain Dart files (or part of Dart files). These will likely be present in
+separate files (`flutter.analysis_options` and `angular.analysis_options`) in
+the near future.
+
+## But what about <lint name>...
+
+We welcome discussions, but the bar for entry for lints here is _very high_ as
+we would run them on automated presubmits (i.e. block PRs where a single lint
+fails) for all Dart projects.