From 0443daf42878ecdef6621d71e1b58d657630299b Mon Sep 17 00:00:00 2001 From: Kenzie Davisson Date: Wed, 15 Apr 2026 14:10:53 -0700 Subject: [PATCH 1/9] Add customization for Gemini Code Assist behavior. --- .gemini/config.yaml | 28 ++++++++++++++++++++++++++++ .gitignore | 3 --- 2 files changed, 28 insertions(+), 3 deletions(-) create mode 100644 .gemini/config.yaml diff --git a/.gemini/config.yaml b/.gemini/config.yaml new file mode 100644 index 00000000000..25c4a8475a1 --- /dev/null +++ b/.gemini/config.yaml @@ -0,0 +1,28 @@ +# Customize Gemini Code Assist behavior for DevTools. +# +# Schema: https://developers.google.com/gemini-code-assist/docs/customize-repo-review#config.yaml-schema +# Based on Flutter config: https://github.com/flutter/flutter/blob/master/.gemini/config.yaml + +# Minimize verbosity. +have_fun: false + +code_review: + # (DEFAULT) - Include field in the config for easy shut off if needed. + disable: false + # LOW, MEDIUM, HIGH or CRITICAL. + comment_severity_threshold: MEDIUM + # (DEFAULT) -1 is unlimited. + max_review_comments: -1 + pull_request_opened: + # (DEFAULT) Explicitly set help to false in case the default changes in the + # future, as having a help message on every PR would be spammy. + help: false + # These tend to be verbose, and since we expect PR authors to clearly + # describe their PRs this would be at best duplicative. + summary: false + # Avoid comments on draft PRs. + include_drafts: false + +ignore_patterns: + # Ignore third party files by default + - "**/third_party/**" diff --git a/.gitignore b/.gitignore index 2a119978514..fc6c1605c17 100644 --- a/.gitignore +++ b/.gitignore @@ -43,9 +43,6 @@ DEPENDENCIES.md **/logs/** *.stager_app.g.dart -# Ignore Gemini logs -**/.gemini/ - # Ignore VS code workspaces that may be configured per-user *.code-workspace From bd3c90f44d3b8b4644c5abc673ccffbec93dd386 Mon Sep 17 00:00:00 2001 From: Kenzie Davisson Date: Wed, 15 Apr 2026 16:16:38 -0700 Subject: [PATCH 2/9] fix grammar in STYLE.md --- STYLE.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/STYLE.md b/STYLE.md index 878461888fb..d898886528f 100644 --- a/STYLE.md +++ b/STYLE.md @@ -6,14 +6,14 @@ found in the LICENSE file or at https://developers.google.com/open-source/licens # DevTools style guide We fully follow [Effective Dart](https://dart.dev/effective-dart) -and some items of -[Style guide for Flutter repo](https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md): +and certain guidelines from the +[Flutter repository style guide](https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md): ## Order of getters and setters -When an object owns and exposes a (listenable) value, -more complicated than just public field -we declare the related class members always in the same order, +When an object owns and exposes a (listenable) value +that is more complex than a simple public field, +we always declare the related class members in the same order, without new lines separating the members, in compliance with [Flutter repo style guide](https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md#order-other-class-members-in-a-way-that-makes-sense): @@ -41,10 +41,10 @@ converted to paths when required to interact with the file system. Additionally: -- `Uri.parse()` should not be used for converting file paths to URIs, instead - `Uri.file()` should be used -- `Uri.path` should not be used for extracting a file path from a URI, instead - `uri.toFilePath()` should be used +- `Uri.parse()` should not be used for converting file paths to URIs; instead, + `Uri.file()` should be used. +- `Uri.path` should not be used for extracting a file path from a URI; instead, + `uri.toFilePath()` should be used. - In code compiled to run in the browser, `Uri.file()` and `uri.toFilePath()` will assume POSIX-style paths even on Windows, so care should be taken to handle these correctly (if possible, avoid converting between URIs and file From 0878403905aec71a624652666853d1c424a7f659 Mon Sep 17 00:00:00 2001 From: Kenzie Davisson Date: Wed, 15 Apr 2026 16:16:47 -0700 Subject: [PATCH 3/9] styleguide.md first pass --- .gemini/styleguide.md | 77 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 .gemini/styleguide.md diff --git a/.gemini/styleguide.md b/.gemini/styleguide.md new file mode 100644 index 00000000000..a11fc81a204 --- /dev/null +++ b/.gemini/styleguide.md @@ -0,0 +1,77 @@ +# DevTools Style Guide for Gemini Code Assist + +This style guide outlines the coding conventions for the DevTools repository to help Gemini Code Assist provide effective code reviews. It is based on repository-specific constraints and existing documentation. + +**Persona**: You are an expert Dart and Flutter developer rooted in best practices. Act as a principal engineer reviewing code, ensuring high quality and adherence to repository conventions. + +## 1. AI Review Protocol (Noise Reduction) + +- **Zero-Formatting Policy:** Do NOT comment on indentation, spacing, or brace placement. We use `dart format` +and the CI testing ensures that the code is formatted correctly. +- **Categorize Severity:** Prefix every comment with a severity: + - `[MUST-FIX]`: Security holes, import violations, or logical bugs. + - `[CONCERN]`: Maintainability issues, high duplication, or "clever" code that is hard to read. + - `[NIT]`: Idiomatic improvements or minor naming suggestions. +- **Focus:** Prioritize logic, performance on the UI thread, and architectural consistency. +- **No Empty Praise:** Do not leave "Looks good" or "Nice change" comments. If there are no issues, leave no comments. +- **Copyright Headers:** Ensure all new files have a proper copyright header with the current year. For example: + ``` + // Copyright 2026 The Flutter Authors + // Use of this source code is governed by a BSD-style license that can be + // found in the LICENSE file or at https://developers.google.com/open-source/licenses/bsd. + ``` + Flag missing copyright headers as `[MUST-FIX]`. + +## 2. Key Principles + +* **Readability**: Code should be easy to understand for all contributors. +* **Maintainability**: Code should be easy to modify and extend without breaking other screens. +* **Consistency**: Adhering to consistent style across all DevTools packages improves collaboration and reduces errors. +* **Code Reuse**: Use shared primitives and components rather than recreating them from scratch. + +## 3. Guidelines from Existing Documentation + +Please refer to the following files for specific rules: + +* **General Style Context**: See [STYLE.md](STYLE.md) for rules on: + * Getter and setter order. + * Naming for typedefs and function variables. + * Overriding equality. + * Windows/POSIX path handling conventions. + * Default text styles. +* **Repository Constraints**: See [AGENTS.md](AGENTS.md) for rules on: + * Constraints on `packages/devtools_shared` (no Flutter dependency). + * Import restrictions (no importing `devtools_app.dart` from `src/`). + * Strict avoidance of raw values in UI (use named constants). + * Usage of established themes and text styles. + * Usage of shared components and utilities. + +## Bot Review Focus + +When reviewing code, Gemini Code Assist should pay special attention to: + +### Dependencies and Imports +* Ensure no Flutter dependencies creep into `packages/devtools_shared`. +* Regarding the packages that are published on pub (`packages/devtools_shared`, +`packages/devtools_app_shared`, `packages/devtools_extensions`): + * Ensure changes are documented in the respective `CHANGELOG.md` files. + * If version bumps are required for these changes, ensure the version + numbers in the respective `pubspec.yaml` files have been updated accordingly. + * Thorougly review changes to these packages to ensure no breaking changes have + been introduced. If a breaking change was introduced, the PR author should + acknowledge that this was in fact intentional and that they are aware of the + implications. + * The published packages should not depend on unpublished packages like + `packages/devtools_app` and `packages/devtools_test`. + +### UI Development +* Flag hardcoded magic strings or numbers used in the interface. +* Flag new style declarations. Wherever possible, prefer using existing + styles from `packages/devtools_app_shared/lib/src/ui/theme/theme.dart`. +* Encourage the reuse of components described in `packages/devtools_app/lib/src/shared/ui/common_widgets.dart`, primitives in `shared/primitives/`, and utilities in `shared/utils/`. +* Verify that themes are accessed using existing patterns. + +## Tooling + +* Code must be formatted with `flutter format`. +* There must be no analysis errors or warnings. From 4790ebba3a3ac6290b55bca05cb19bcd9f8af019 Mon Sep 17 00:00:00 2001 From: Kenzie Davisson Date: Wed, 15 Apr 2026 16:19:48 -0700 Subject: [PATCH 4/9] deduplicate --- .gemini/styleguide.md | 28 ---------------------------- AGENTS.md | 6 ++++++ 2 files changed, 6 insertions(+), 28 deletions(-) diff --git a/.gemini/styleguide.md b/.gemini/styleguide.md index a11fc81a204..088740dc7cb 100644 --- a/.gemini/styleguide.md +++ b/.gemini/styleguide.md @@ -46,32 +46,4 @@ Please refer to the following files for specific rules: * Usage of established themes and text styles. * Usage of shared components and utilities. -## Bot Review Focus -When reviewing code, Gemini Code Assist should pay special attention to: - -### Dependencies and Imports -* Ensure no Flutter dependencies creep into `packages/devtools_shared`. -* Regarding the packages that are published on pub (`packages/devtools_shared`, -`packages/devtools_app_shared`, `packages/devtools_extensions`): - * Ensure changes are documented in the respective `CHANGELOG.md` files. - * If version bumps are required for these changes, ensure the version - numbers in the respective `pubspec.yaml` files have been updated accordingly. - * Thorougly review changes to these packages to ensure no breaking changes have - been introduced. If a breaking change was introduced, the PR author should - acknowledge that this was in fact intentional and that they are aware of the - implications. - * The published packages should not depend on unpublished packages like - `packages/devtools_app` and `packages/devtools_test`. - -### UI Development -* Flag hardcoded magic strings or numbers used in the interface. -* Flag new style declarations. Wherever possible, prefer using existing - styles from `packages/devtools_app_shared/lib/src/ui/theme/theme.dart`. -* Encourage the reuse of components described in `packages/devtools_app/lib/src/shared/ui/common_widgets.dart`, primitives in `shared/primitives/`, and utilities in `shared/utils/`. -* Verify that themes are accessed using existing patterns. - -## Tooling - -* Code must be formatted with `flutter format`. -* There must be no analysis errors or warnings. diff --git a/AGENTS.md b/AGENTS.md index dbefc78281f..2bdafcf2cb2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,6 +8,12 @@ Follow these rules when working in this repository. - **`packages/devtools_shared`**: Never introduce a Flutter dependency or a dependency on web-only Dart libraries. - **Imports**: Never import `packages/devtools_app/lib/devtools_app.dart` in code under `packages/devtools_app/lib/src/`. It is acceptable in test code. +### Published Packages (`packages/devtools_shared`, `packages/devtools_app_shared`, `packages/devtools_extensions`) +- Document file changes in the respective `CHANGELOG.md` files. +- Ensure version numbers in `pubspec.yaml` are updated accordingly for required changes. +- Ensure no breaking changes are introduced. If introduced, they must be intentional and documented. +- The published packages should not depend on unpublished packages like `packages/devtools_app` and `packages/devtools_test`. + ### Code Style - **Style Guide**: Follow the DevTools style guide in [STYLE.md](STYLE.md). - **Formatting & Analysis**: Always ensure code is formatted properly and has no analysis errors or warnings before completing a task. From fd21472f87550e381629f2cad9ddb483a440ef0d Mon Sep 17 00:00:00 2001 From: Kenzie Davisson Date: Wed, 15 Apr 2026 16:24:09 -0700 Subject: [PATCH 5/9] more quality guidance --- .gemini/styleguide.md | 2 -- AGENTS.md | 8 ++++++++ 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/.gemini/styleguide.md b/.gemini/styleguide.md index 088740dc7cb..e38b5923fb8 100644 --- a/.gemini/styleguide.md +++ b/.gemini/styleguide.md @@ -45,5 +45,3 @@ Please refer to the following files for specific rules: * Strict avoidance of raw values in UI (use named constants). * Usage of established themes and text styles. * Usage of shared components and utilities. - - diff --git a/AGENTS.md b/AGENTS.md index 2bdafcf2cb2..1500ec6ef91 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,6 +18,11 @@ Follow these rules when working in this repository. - **Style Guide**: Follow the DevTools style guide in [STYLE.md](STYLE.md). - **Formatting & Analysis**: Always ensure code is formatted properly and has no analysis errors or warnings before completing a task. +### Code Quality & Maintainability +- **DRY (Don't Repeat Yourself)**: Identify blocks of code that are 90%+ identical to existing utility methods in this repo and flag them for duplication. +- **Meaningful Naming**: Variables should describe their intent (e.g., `timeoutInMs` instead of `t`). +- **Descriptive Pull Request**: Contributors should include the information recommended in the pull request template (In `.github/PULL_REQUEST_TEMPLATE.md`). + ## Running Tests - **Standard Packages**: Run unit and widget tests with `flutter test`. @@ -40,3 +45,6 @@ Follow these rules when working in this repository. ### Code Reuse - **Use Shared Components & Utils**: Prefer using reusable components from `shared/ui/` (such as `packages/devtools_app/lib/src/shared/ui/common_widgets.dart`), primitives from `shared/primitives/`, and utilities from `shared/utils/` rather than creating things from scratch. +### Helper Widgets and Methods +- **Avoid Long Build Methods**: Use separate helper widgets instead of writing excessively long build methods to keep the structure clear. +- **Prefer Widgets Over Methods**: Create small, composable helper widgets rather than helper methods that return a widget at build time. This improves readability and allows Flutter to optimize tree updates better. From 5c4e661c4e59dddd6f80a72f19f01cdb6511e86b Mon Sep 17 00:00:00 2001 From: Kenzie Davisson Date: Wed, 15 Apr 2026 16:30:47 -0700 Subject: [PATCH 6/9] tweaks --- .gemini/styleguide.md | 4 ++++ AGENTS.md | 6 +----- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.gemini/styleguide.md b/.gemini/styleguide.md index e38b5923fb8..fd0b7d6800d 100644 --- a/.gemini/styleguide.md +++ b/.gemini/styleguide.md @@ -28,6 +28,7 @@ and the CI testing ensures that the code is formatted correctly. * **Maintainability**: Code should be easy to modify and extend without breaking other screens. * **Consistency**: Adhering to consistent style across all DevTools packages improves collaboration and reduces errors. * **Code Reuse**: Use shared primitives and components rather than recreating them from scratch. +* **Testing**: All changes should include automated tests to ensure correctness and prevent regressions. ## 3. Guidelines from Existing Documentation @@ -42,6 +43,9 @@ Please refer to the following files for specific rules: * **Repository Constraints**: See [AGENTS.md](AGENTS.md) for rules on: * Constraints on `packages/devtools_shared` (no Flutter dependency). * Import restrictions (no importing `devtools_app.dart` from `src/`). + * Published packages management (CHANGELOGs, versions, breaking changes). + * Code quality (Single Responsibility, DRY, Meaningful Naming). * Strict avoidance of raw values in UI (use named constants). * Usage of established themes and text styles. * Usage of shared components and utilities. + * Widget structure (avoiding long build methods, widgets vs methods). diff --git a/AGENTS.md b/AGENTS.md index 1500ec6ef91..eeb00698d57 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,20 +19,16 @@ Follow these rules when working in this repository. - **Formatting & Analysis**: Always ensure code is formatted properly and has no analysis errors or warnings before completing a task. ### Code Quality & Maintainability +- **Single Responsibility**: Methods should ideally be 10-20 lines. If a method exceeds 30 lines, suggest a refactor. - **DRY (Don't Repeat Yourself)**: Identify blocks of code that are 90%+ identical to existing utility methods in this repo and flag them for duplication. - **Meaningful Naming**: Variables should describe their intent (e.g., `timeoutInMs` instead of `t`). - **Descriptive Pull Request**: Contributors should include the information recommended in the pull request template (In `.github/PULL_REQUEST_TEMPLATE.md`). ## Running Tests - - **Standard Packages**: Run unit and widget tests with `flutter test`. - **`packages/devtools_shared`**: Run tests with `dart test`. - **Integration Tests**: Refer to the [Integration Test README](packages/devtools_app/integration_test/README.md) for instructions on running integration tests. -## Tooling Best Practices - -- **MCP Tools**: Prefer using MCP server tools over shell commands whenever possible. - ## UI Development Guidelines ### Constants and Magic Values From f7700503dfc27e5960ec9d08eef16212686e39a6 Mon Sep 17 00:00:00 2001 From: Kenzie Davisson Date: Wed, 15 Apr 2026 16:32:05 -0700 Subject: [PATCH 7/9] add documentation rules --- AGENTS.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index eeb00698d57..32426a3975c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,6 +24,13 @@ Follow these rules when working in this repository. - **Meaningful Naming**: Variables should describe their intent (e.g., `timeoutInMs` instead of `t`). - **Descriptive Pull Request**: Contributors should include the information recommended in the pull request template (In `.github/PULL_REQUEST_TEMPLATE.md`). +## Documentation +- All public members should have documentation. +- **Answer your own questions**: If you have a question, find the answer, and then document it where you first looked. +- **Documentation should be useful**: Explain the *why* and the *how*. +- **Introduce terms**: Assume the reader does not know everything. Link to definitions. +- Use `///` for public-quality documentation, even on private members. + ## Running Tests - **Standard Packages**: Run unit and widget tests with `flutter test`. - **`packages/devtools_shared`**: Run tests with `dart test`. From 7955d76bc18cd3fd7174c8004fb1baafb637f129 Mon Sep 17 00:00:00 2001 From: Kenzie Davisson Date: Wed, 15 Apr 2026 16:41:46 -0700 Subject: [PATCH 8/9] remove single responsibility --- .gemini/styleguide.md | 2 +- AGENTS.md | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/.gemini/styleguide.md b/.gemini/styleguide.md index fd0b7d6800d..83f7bbb94c7 100644 --- a/.gemini/styleguide.md +++ b/.gemini/styleguide.md @@ -44,7 +44,7 @@ Please refer to the following files for specific rules: * Constraints on `packages/devtools_shared` (no Flutter dependency). * Import restrictions (no importing `devtools_app.dart` from `src/`). * Published packages management (CHANGELOGs, versions, breaking changes). - * Code quality (Single Responsibility, DRY, Meaningful Naming). + * Code quality (DRY, Meaningful Naming). * Strict avoidance of raw values in UI (use named constants). * Usage of established themes and text styles. * Usage of shared components and utilities. diff --git a/AGENTS.md b/AGENTS.md index 32426a3975c..c182f48298f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,7 +19,6 @@ Follow these rules when working in this repository. - **Formatting & Analysis**: Always ensure code is formatted properly and has no analysis errors or warnings before completing a task. ### Code Quality & Maintainability -- **Single Responsibility**: Methods should ideally be 10-20 lines. If a method exceeds 30 lines, suggest a refactor. - **DRY (Don't Repeat Yourself)**: Identify blocks of code that are 90%+ identical to existing utility methods in this repo and flag them for duplication. - **Meaningful Naming**: Variables should describe their intent (e.g., `timeoutInMs` instead of `t`). - **Descriptive Pull Request**: Contributors should include the information recommended in the pull request template (In `.github/PULL_REQUEST_TEMPLATE.md`). From e091fd2935df2da38ecd694bd1bf9bb57b57687b Mon Sep 17 00:00:00 2001 From: Kenzie Davisson <43759233+kenzieschmoll@users.noreply.github.com> Date: Wed, 15 Apr 2026 16:49:53 -0700 Subject: [PATCH 9/9] Update AGENTS.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index c182f48298f..218ad3bf918 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,7 +21,7 @@ Follow these rules when working in this repository. ### Code Quality & Maintainability - **DRY (Don't Repeat Yourself)**: Identify blocks of code that are 90%+ identical to existing utility methods in this repo and flag them for duplication. - **Meaningful Naming**: Variables should describe their intent (e.g., `timeoutInMs` instead of `t`). -- **Descriptive Pull Request**: Contributors should include the information recommended in the pull request template (In `.github/PULL_REQUEST_TEMPLATE.md`). +- **Descriptive Pull Request**: Contributors should include the information recommended in the pull request template (in `.github/PULL_REQUEST_TEMPLATE.md`). ## Documentation - All public members should have documentation.