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/.gemini/styleguide.md b/.gemini/styleguide.md new file mode 100644 index 00000000000..83f7bbb94c7 --- /dev/null +++ b/.gemini/styleguide.md @@ -0,0 +1,51 @@ +# 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. +* **Testing**: All changes should include automated tests to ensure correctness and prevent regressions. + +## 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/`). + * Published packages management (CHANGELOGs, versions, breaking changes). + * 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. + * Widget structure (avoiding long build methods, widgets vs methods). 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 diff --git a/AGENTS.md b/AGENTS.md index dbefc78281f..218ad3bf918 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,20 +8,33 @@ 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. -## Running Tests +### 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`). + +## 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`. - **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 @@ -34,3 +47,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. 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