From 3d000b570cc51bd05cd49033d04650d3c26e691d Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Mon, 14 Sep 2026 22:15:59 +0200 Subject: [PATCH] Try out a style guide for gemini-code-assist reviews --- .gemini/styleguide.md | 123 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 .gemini/styleguide.md diff --git a/.gemini/styleguide.md b/.gemini/styleguide.md new file mode 100644 index 00000000000..6c835452229 --- /dev/null +++ b/.gemini/styleguide.md @@ -0,0 +1,123 @@ +# Pull request review guide + +This repository contains the source and content for +the `docs.flutter.dev` and `flutter.dev` websites. +Both are static sites built with Dart and Jaspr, +with most content authored in Markdown. + +Review changes for concrete problems that affect readers, contributors, +or the built websites, within the pull request's intended scope. + +## Report only what matters + +Report an issue only if the change introduces or worsens it, +it's of medium severity or higher, +and you can state its concrete consequence. +Read the surrounding code and content before commenting. + +Prioritize: + +- Incorrect instructions, commands, API names, or expected results. +- Broken or misleading examples and behavior regressions. +- Navigation, rendering, accessibility, or security defects. + +Don't report: + +- Preference-only rewrites, cosmetic nits, speculative optimizations, + or refactoring and architecture changes outside the PR's scope. +- Generic best-practice reminders not tied to a specific defect in the diff. +- Issues already raised by existing review comments or automated checks, + unless you add useful context. + +Keep comments focused and intentional. +Include the problem, its consequence, +and the smallest useful fix, ideally as a suggestion block. +Skip praise, background, and tutorials. +Consolidate repeated instances of the same issue into one comment. +Never claim to have run checks or consulted sources you couldn't access. + +## Respect the repository structure and each example's purpose + +- `sites/docs/` and `sites/www/` are Jaspr websites, not Flutter apps. + Don't apply Flutter widget or lifecycle rules to Jaspr components. +- `examples/` is a separate pub workspace of documentation samples. + Samples are deliberately minimal. + Read the surrounding explanation before flagging omitted boilerplate, + omitted error handling, lint suppressions, + or code explicitly labeled as incorrect or outdated, + such as in migration guides. +- `` blocks are generated from `examples/`. + Check the referenced source and any excerpt transformations + before calling a snippet incomplete. + Suggest fixing the source or directive and refreshing the excerpt, + not editing the generated Markdown. + +## Assume Dart 3.13 + +Unless otherwise specified, +all code in this repository is written for +Dart **3.13** and the corresponding Flutter release. +Treat every feature in that version as stable and available, +even if it's newer than what you're familiar with. +Don't request compatibility with older SDKs. + +The following syntax is valid and intentional. +Never flag it as an error, typo, duplicate name, or missing type: + +- Primary constructors: `class Point(final int x, final int y);` +- Concise constructor declarations: + `new(this.x, this.y);`, `new origin() : x = 0, y = 0;`, + and `factory parse(String source) { ... }`. +- Private named initializing formals: `Config({required this._theme});`, + called with the public argument `Config(theme: ...)`. +- Dot shorthands: `.center`, `.new()`, and `.idle => value` + when the context supplies the type. +- Null-aware collection elements: `[?maybeNull]`. +- Wildcards: `_` doesn't bind, so `(_, _) => 0` and `catch (_)` are valid. +- Digit separators (`1_000_000`), extension types, records, patterns, + switch expressions, class modifiers, and private final field promotion. + +For unfamiliar syntax, consult +before claiming it's invalid or recommending an older form. +If you can't verify a suspected error, omit the claim. +Let the existing `dart format` and `dart analyze` checks +handle layout, trailing commas, and lint-level style. + +## Dart conventions + +Dart code follows Effective Dart, +except where an example deliberately deviates to teach a concept. + +- Avoid `dynamic`, implicit dynamic calls, and other escapes from + static checking, unless the surrounding explanation calls for them. +- Don't request redundant type annotations, casts, `!`, + or `default` and `_` cases in exhaustive switches + over enums or sealed types. +- Futures should be awaited, returned, + or deliberately detached with `unawaited` and a comment explaining why. +- Don't request tests. + This repository doesn't require them, + except in examples that specifically demonstrate testing. + +## Documentation and Markdown + +Don't flag: + +- Jaspr Content and site conventions. + We use YAML front matter, Liquid expressions, `:::note`-style alerts, + definition lists, custom components, raw HTML, + and a body without an H1, which the layout supplies. +- Line wrapping. + New prose uses semantic line breaks with lines under 80 characters, + but deviations are ok for blog posts and low severity in general. +- Blog voice. + First person, humor, and future-facing announcements are valid in posts. + +Documentation prose, but not blog posts, +follows the Google developer documentation style guide +with some local additions and deviations, +such as introducing links with "refer to", "consult", +"check out", or "visit" rather than "see". +When existing content consistently differs from the style guide, +treat that as an intentional convention and match it. +Apply the same style to any replacement prose you propose.