{"owner":"flutter","repo":"packages","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Agent Guide for the Flutter Packages Repository\n\nThis document provides guidance for AI agents to effectively contribute to the `flutter/packages` repository.\n\n## Guiding Principles for Contributions\n\n- **Format All Code**: Every code change must be formatted using the repository's tools.\n- **Pass All Tests**: All changes must pass linting, analysis, and relevant tests.\n- **Update CHANGELOGs**: Any user-facing change or bug fix in a package requires an update to its `CHANGELOG.md` and `pubspec.yaml` version. Ensure you follow the [CHANGELOG style guide](https://github.com/flutter/flutter/blob/master/docs/ecosystem/contributing/README.md#changelog-style).\n- **Follow Conventions**: Adhere to the repository's specific conventions, such as federated plugin structure and code generation steps.\n\n## Agent Environment Setup\n\nTo ensure a consistent and functional environment, configure your VM with the following setup. This provides the necessary Flutter SDK and dependencies for building and testing packages.\n\n```bash\ncurl -L https://storage.googleapis.com/flutter_infra_release/releases/stable/linux/flutter_linux_3.32.8-stable.tar.xz | tar -xJ -C $HOME\nexport FLUTTER_HOME=$HOME/flutter\nexport PATH=$FLUTTER_HOME/bin:$PATH\nflutter --disable-analytics\nflutter precache --force\n# Sanity check the configuration.\nflutter doctor --verbose\n```\n\n## Repository Overview\n\nThis is a monorepo containing many Flutter packages.\n- First-party packages developed entirely by the Flutter team are in `packages/`.\n- Packages that were originally developed by a third party, but are now maintained by the Flutter team are in `third_party/packages/`.\n- The repository tooling is in `script/tool/`.\n\nMany packages are part of **federated plugins**. A federated plugin has a main package (e.g., `path_provider`) that defines the API used by plugin clients, a platform interface package (e.g., `path_provider_platform_interface`) that defines the interface that each platform implementation must implement, and one or more platform implementation packages (e.g., `path_provider_android`, `path_provider_ios`) that implement that platform interface. When working on a federated plugin, you may need to modify multiple packages.\n\nFor more details, see the main `README.md` and `CONTRIBUTING.md`.\n\n## Core Tooling and Workflows\n\nThe primary tool for this repository is `flutter_plugin_tools.dart`.\n\n### Initial Setup\n\nFirst, define an environment variable for the repository root directory and initialize the tooling:\n```bash\n# Define an environment variable for the repository root.\nexport REPO_ROOT=$(pwd)\n\n# Verify that the environment variable is working correctly.\necho \"Repository root directory: $REPO_ROOT\"\n\ndart pub get -C $REPO_ROOT/script/tool\n```\n\n### Identifying Target Packages\n\nMost tool commands take a `--packages` argument. You must correctly identify all packages affected by your changes. You can derive this from git diff.\n\nFor example, to find changed files against the main branch of the upstream remote (assuming the upstream remote is named `origin`):\n\n```bash\ngit diff --name-only origin/main...HEAD\n```\n\nThen, for each file path, find its enclosing package. A package is a directory containing a `pubspec.yaml` file. The directory name is usually the package name. Ignore `pubspec.yaml` files within `example/` directories when determining the package for a file.\n\n#### Targeting All Packages\n\nRunning a tool command without a `--packages` argument will run the command on all packages. For example, a dependency can be updated for all packages in the repository:\n\n```bash\ndart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart update-dependency --pub-package <dependency_name>\n```\n\n### Common Commands\n\n- **Formatting**: Always format your changes.\n\n  ```bash\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart format --packages <changed_packages>\n  ```\n- **Testing**: All changes must pass analysis and tests:\n\n  ```bash\n  # Run static analysis\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart analyze --packages <changed_packages>\n  # Run Dart unit tests\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart dart-test --packages <changed_packages>\n  ```\n\n  The tool can also run native and integration tests, but these may require a more complete environment than is available.\n- **Validation**: Run these checks to ensure that changes follow team guidelines:\n  ```bash\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart validate --packages <changed_packages>\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart publish-check --packages <changed_packages>\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart license-check\n  ```\n\n### Specialized Workflows\n\n- **Federated Plugin Development**: If you change multiple packages in a federated plugin that depend on each other, use `make-deps-path-based` to make their pubspec.yaml files use `path:` dependencies. This allows you to test them together locally.\n  ```bash\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart make-deps-path-based --target-dependencies=<changed_plugin_packages>\n  ```\n\n  The CI system will run tests with path-based dependencies automatically, so this is not required for PRs, but can be useful for local testing.\n- **Updating Dependencies**: To update a dependency across multiple packages:\n  ```bash\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart update-dependency --pub-package <dependency_name> --packages <packages_to_update>\n  ```\n- **Updating README Code Samples**: If you change example code that is included in a README.md:\n  ```bash\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart update-excerpts --packages <changed_packages>\n  ```\n\n## Code Generators\n\nSome packages use code generators, and changes to those packages require running the relevant code generators.\n\n- **Pigeon**: If you change a file in a `pigeons/` directory, you must run the Pigeon generator:\n  ```bash\n  # Run from the package's directory\n  dart run pigeon --input pigeons/<changed_file>.dart\n  ```\n- **Mockito**: If you change code in a package that uses `mockito` for tests (check `dev_dependencies` in `pubspec.yaml`), you must run its mock generator:\n  ```bash\n  # Run from the package's directory\n  dart run build_runner build -d\n  ```\n\n## Code Style\n\nAll code must adhere to the repository's style guides. The `format` command handles most of this, but be aware of the specific style guides for each language, as detailed in [CONTRIBUTING.md](./CONTRIBUTING.md#style):\n- **Dart**: Flutter style, formatted with `dart format`.\n- **C++**: Google style, formatted with `clang-format`.\n- **Java**: Google style, formatted with `google-java-format`.\n- **Kotlin**: Android Kotlin style, formatted with `ktfmt`.\n- **Objective-C**: Google style, formatted with `clang-format`.\n- **Swift**: Google style, formatted with `swift-format`.\n- **Comments**: Avoid adding redundant or trivial comments that simply restate what the code itself does (e.g., repeating method calls in English). Comments should explain the *why* behind complex or non-obvious logic, or serve as public API documentation.\n\n## Version and CHANGELOG updates\n\nAny PR that changes non-test code in a package should update its version in pubspec.yaml and add a corresponding entry in CHANGELOG.md.\n\n**This process can be automated**. The `update-release-info` command is the preferred way to handle this. It determines changed packages, bumps versions, and updates changelogs automatically.\n```bash\ndart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart update-release-info \\\n  --version=minimal \\\n  --base-branch=origin/main \\\n  --changelog=\"A description of the changes.\"\n```\n\n- `--version=minimal`: Bumps patch for bug fixes, and skips unchanged packages. This is usually the best option unless a new feature is being added.\n  - When making public API changes, use `--version=minor` instead.\n- `--base-branch=origin/main`: Diffs against the `main` branch to find changed packages.\n\nIf you update manually, follow semantic versioning and the [repository's CHANGELOG style](https://github.com/flutter/flutter/blob/master/docs/ecosystem/contributing/README.md#changelog-style).\n"},"files":{"AGENTS.md":"# Agent Guide for the Flutter Packages Repository\n\nThis document provides guidance for AI agents to effectively contribute to the `flutter/packages` repository.\n\n## Guiding Principles for Contributions\n\n- **Format All Code**: Every code change must be formatted using the repository's tools.\n- **Pass All Tests**: All changes must pass linting, analysis, and relevant tests.\n- **Update CHANGELOGs**: Any user-facing change or bug fix in a package requires an update to its `CHANGELOG.md` and `pubspec.yaml` version. Ensure you follow the [CHANGELOG style guide](https://github.com/flutter/flutter/blob/master/docs/ecosystem/contributing/README.md#changelog-style).\n- **Follow Conventions**: Adhere to the repository's specific conventions, such as federated plugin structure and code generation steps.\n\n## Agent Environment Setup\n\nTo ensure a consistent and functional environment, configure your VM with the following setup. This provides the necessary Flutter SDK and dependencies for building and testing packages.\n\n```bash\ncurl -L https://storage.googleapis.com/flutter_infra_release/releases/stable/linux/flutter_linux_3.32.8-stable.tar.xz | tar -xJ -C $HOME\nexport FLUTTER_HOME=$HOME/flutter\nexport PATH=$FLUTTER_HOME/bin:$PATH\nflutter --disable-analytics\nflutter precache --force\n# Sanity check the configuration.\nflutter doctor --verbose\n```\n\n## Repository Overview\n\nThis is a monorepo containing many Flutter packages.\n- First-party packages developed entirely by the Flutter team are in `packages/`.\n- Packages that were originally developed by a third party, but are now maintained by the Flutter team are in `third_party/packages/`.\n- The repository tooling is in `script/tool/`.\n\nMany packages are part of **federated plugins**. A federated plugin has a main package (e.g., `path_provider`) that defines the API used by plugin clients, a platform interface package (e.g., `path_provider_platform_interface`) that defines the interface that each platform implementation must implement, and one or more platform implementation packages (e.g., `path_provider_android`, `path_provider_ios`) that implement that platform interface. When working on a federated plugin, you may need to modify multiple packages.\n\nFor more details, see the main `README.md` and `CONTRIBUTING.md`.\n\n## Core Tooling and Workflows\n\nThe primary tool for this repository is `flutter_plugin_tools.dart`.\n\n### Initial Setup\n\nFirst, define an environment variable for the repository root directory and initialize the tooling:\n```bash\n# Define an environment variable for the repository root.\nexport REPO_ROOT=$(pwd)\n\n# Verify that the environment variable is working correctly.\necho \"Repository root directory: $REPO_ROOT\"\n\ndart pub get -C $REPO_ROOT/script/tool\n```\n\n### Identifying Target Packages\n\nMost tool commands take a `--packages` argument. You must correctly identify all packages affected by your changes. You can derive this from git diff.\n\nFor example, to find changed files against the main branch of the upstream remote (assuming the upstream remote is named `origin`):\n\n```bash\ngit diff --name-only origin/main...HEAD\n```\n\nThen, for each file path, find its enclosing package. A package is a directory containing a `pubspec.yaml` file. The directory name is usually the package name. Ignore `pubspec.yaml` files within `example/` directories when determining the package for a file.\n\n#### Targeting All Packages\n\nRunning a tool command without a `--packages` argument will run the command on all packages. For example, a dependency can be updated for all packages in the repository:\n\n```bash\ndart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart update-dependency --pub-package <dependency_name>\n```\n\n### Common Commands\n\n- **Formatting**: Always format your changes.\n\n  ```bash\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart format --packages <changed_packages>\n  ```\n- **Testing**: All changes must pass analysis and tests:\n\n  ```bash\n  # Run static analysis\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart analyze --packages <changed_packages>\n  # Run Dart unit tests\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart dart-test --packages <changed_packages>\n  ```\n\n  The tool can also run native and integration tests, but these may require a more complete environment than is available.\n- **Validation**: Run these checks to ensure that changes follow team guidelines:\n  ```bash\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart validate --packages <changed_packages>\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart publish-check --packages <changed_packages>\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart license-check\n  ```\n\n### Specialized Workflows\n\n- **Federated Plugin Development**: If you change multiple packages in a federated plugin that depend on each other, use `make-deps-path-based` to make their pubspec.yaml files use `path:` dependencies. This allows you to test them together locally.\n  ```bash\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart make-deps-path-based --target-dependencies=<changed_plugin_packages>\n  ```\n\n  The CI system will run tests with path-based dependencies automatically, so this is not required for PRs, but can be useful for local testing.\n- **Updating Dependencies**: To update a dependency across multiple packages:\n  ```bash\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart update-dependency --pub-package <dependency_name> --packages <packages_to_update>\n  ```\n- **Updating README Code Samples**: If you change example code that is included in a README.md:\n  ```bash\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart update-excerpts --packages <changed_packages>\n  ```\n\n## Code Generators\n\nSome packages use code generators, and changes to those packages require running the relevant code generators.\n\n- **Pigeon**: If you change a file in a `pigeons/` directory, you must run the Pigeon generator:\n  ```bash\n  # Run from the package's directory\n  dart run pigeon --input pigeons/<changed_file>.dart\n  ```\n- **Mockito**: If you change code in a package that uses `mockito` for tests (check `dev_dependencies` in `pubspec.yaml`), you must run its mock generator:\n  ```bash\n  # Run from the package's directory\n  dart run build_runner build -d\n  ```\n\n## Code Style\n\nAll code must adhere to the repository's style guides. The `format` command handles most of this, but be aware of the specific style guides for each language, as detailed in [CONTRIBUTING.md](./CONTRIBUTING.md#style):\n- **Dart**: Flutter style, formatted with `dart format`.\n- **C++**: Google style, formatted with `clang-format`.\n- **Java**: Google style, formatted with `google-java-format`.\n- **Kotlin**: Android Kotlin style, formatted with `ktfmt`.\n- **Objective-C**: Google style, formatted with `clang-format`.\n- **Swift**: Google style, formatted with `swift-format`.\n- **Comments**: Avoid adding redundant or trivial comments that simply restate what the code itself does (e.g., repeating method calls in English). Comments should explain the *why* behind complex or non-obvious logic, or serve as public API documentation.\n\n## Version and CHANGELOG updates\n\nAny PR that changes non-test code in a package should update its version in pubspec.yaml and add a corresponding entry in CHANGELOG.md.\n\n**This process can be automated**. The `update-release-info` command is the preferred way to handle this. It determines changed packages, bumps versions, and updates changelogs automatically.\n```bash\ndart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart update-release-info \\\n  --version=minimal \\\n  --base-branch=origin/main \\\n  --changelog=\"A description of the changes.\"\n```\n\n- `--version=minimal`: Bumps patch for bug fixes, and skips unchanged packages. This is usually the best option unless a new feature is being added.\n  - When making public API changes, use `--version=minor` instead.\n- `--base-branch=origin/main`: Diffs against the `main` branch to find changed packages.\n\nIf you update manually, follow semantic versioning and the [repository's CHANGELOG style](https://github.com/flutter/flutter/blob/master/docs/ecosystem/contributing/README.md#changelog-style).\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Agent Guide for the Flutter Packages Repository\n\nThis document provides guidance for AI agents to effectively contribute to the `flutter/packages` repository.\n\n## Guiding Principles for Contributions\n\n- **Format All Code**: Every code change must be formatted using the repository's tools.\n- **Pass All Tests**: All changes must pass linting, analysis, and relevant tests.\n- **Update CHANGELOGs**: Any user-facing change or bug fix in a package requires an update to its `CHANGELOG.md` and `pubspec.yaml` version. Ensure you follow the [CHANGELOG style guide](https://github.com/flutter/flutter/blob/master/docs/ecosystem/contributing/README.md#changelog-style).\n- **Follow Conventions**: Adhere to the repository's specific conventions, such as federated plugin structure and code generation steps.\n\n## Agent Environment Setup\n\nTo ensure a consistent and functional environment, configure your VM with the following setup. This provides the necessary Flutter SDK and dependencies for building and testing packages.\n\n```bash\ncurl -L https://storage.googleapis.com/flutter_infra_release/releases/stable/linux/flutter_linux_3.32.8-stable.tar.xz | tar -xJ -C $HOME\nexport FLUTTER_HOME=$HOME/flutter\nexport PATH=$FLUTTER_HOME/bin:$PATH\nflutter --disable-analytics\nflutter precache --force\n# Sanity check the configuration.\nflutter doctor --verbose\n```\n\n## Repository Overview\n\nThis is a monorepo containing many Flutter packages.\n- First-party packages developed entirely by the Flutter team are in `packages/`.\n- Packages that were originally developed by a third party, but are now maintained by the Flutter team are in `third_party/packages/`.\n- The repository tooling is in `script/tool/`.\n\nMany packages are part of **federated plugins**. A federated plugin has a main package (e.g., `path_provider`) that defines the API used by plugin clients, a platform interface package (e.g., `path_provider_platform_interface`) that defines the interface that each platform implementation must implement, and one or more platform implementation packages (e.g., `path_provider_android`, `path_provider_ios`) that implement that platform interface. When working on a federated plugin, you may need to modify multiple packages.\n\nFor more details, see the main `README.md` and `CONTRIBUTING.md`.\n\n## Core Tooling and Workflows\n\nThe primary tool for this repository is `flutter_plugin_tools.dart`.\n\n### Initial Setup\n\nFirst, define an environment variable for the repository root directory and initialize the tooling:\n```bash\n# Define an environment variable for the repository root.\nexport REPO_ROOT=$(pwd)\n\n# Verify that the environment variable is working correctly.\necho \"Repository root directory: $REPO_ROOT\"\n\ndart pub get -C $REPO_ROOT/script/tool\n```\n\n### Identifying Target Packages\n\nMost tool commands take a `--packages` argument. You must correctly identify all packages affected by your changes. You can derive this from git diff.\n\nFor example, to find changed files against the main branch of the upstream remote (assuming the upstream remote is named `origin`):\n\n```bash\ngit diff --name-only origin/main...HEAD\n```\n\nThen, for each file path, find its enclosing package. A package is a directory containing a `pubspec.yaml` file. The directory name is usually the package name. Ignore `pubspec.yaml` files within `example/` directories when determining the package for a file.\n\n#### Targeting All Packages\n\nRunning a tool command without a `--packages` argument will run the command on all packages. For example, a dependency can be updated for all packages in the repository:\n\n```bash\ndart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart update-dependency --pub-package <dependency_name>\n```\n\n### Common Commands\n\n- **Formatting**: Always format your changes.\n\n  ```bash\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart format --packages <changed_packages>\n  ```\n- **Testing**: All changes must pass analysis and tests:\n\n  ```bash\n  # Run static analysis\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart analyze --packages <changed_packages>\n  # Run Dart unit tests\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart dart-test --packages <changed_packages>\n  ```\n\n  The tool can also run native and integration tests, but these may require a more complete environment than is available.\n- **Validation**: Run these checks to ensure that changes follow team guidelines:\n  ```bash\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart validate --packages <changed_packages>\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart publish-check --packages <changed_packages>\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart license-check\n  ```\n\n### Specialized Workflows\n\n- **Federated Plugin Development**: If you change multiple packages in a federated plugin that depend on each other, use `make-deps-path-based` to make their pubspec.yaml files use `path:` dependencies. This allows you to test them together locally.\n  ```bash\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart make-deps-path-based --target-dependencies=<changed_plugin_packages>\n  ```\n\n  The CI system will run tests with path-based dependencies automatically, so this is not required for PRs, but can be useful for local testing.\n- **Updating Dependencies**: To update a dependency across multiple packages:\n  ```bash\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart update-dependency --pub-package <dependency_name> --packages <packages_to_update>\n  ```\n- **Updating README Code Samples**: If you change example code that is included in a README.md:\n  ```bash\n  dart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart update-excerpts --packages <changed_packages>\n  ```\n\n## Code Generators\n\nSome packages use code generators, and changes to those packages require running the relevant code generators.\n\n- **Pigeon**: If you change a file in a `pigeons/` directory, you must run the Pigeon generator:\n  ```bash\n  # Run from the package's directory\n  dart run pigeon --input pigeons/<changed_file>.dart\n  ```\n- **Mockito**: If you change code in a package that uses `mockito` for tests (check `dev_dependencies` in `pubspec.yaml`), you must run its mock generator:\n  ```bash\n  # Run from the package's directory\n  dart run build_runner build -d\n  ```\n\n## Code Style\n\nAll code must adhere to the repository's style guides. The `format` command handles most of this, but be aware of the specific style guides for each language, as detailed in [CONTRIBUTING.md](./CONTRIBUTING.md#style):\n- **Dart**: Flutter style, formatted with `dart format`.\n- **C++**: Google style, formatted with `clang-format`.\n- **Java**: Google style, formatted with `google-java-format`.\n- **Kotlin**: Android Kotlin style, formatted with `ktfmt`.\n- **Objective-C**: Google style, formatted with `clang-format`.\n- **Swift**: Google style, formatted with `swift-format`.\n- **Comments**: Avoid adding redundant or trivial comments that simply restate what the code itself does (e.g., repeating method calls in English). Comments should explain the *why* behind complex or non-obvious logic, or serve as public API documentation.\n\n## Version and CHANGELOG updates\n\nAny PR that changes non-test code in a package should update its version in pubspec.yaml and add a corresponding entry in CHANGELOG.md.\n\n**This process can be automated**. The `update-release-info` command is the preferred way to handle this. It determines changed packages, bumps versions, and updates changelogs automatically.\n```bash\ndart run $REPO_ROOT/script/tool/bin/flutter_plugin_tools.dart update-release-info \\\n  --version=minimal \\\n  --base-branch=origin/main \\\n  --changelog=\"A description of the changes.\"\n```\n\n- `--version=minimal`: Bumps patch for bug fixes, and skips unchanged packages. This is usually the best option unless a new feature is being added.\n  - When making public API changes, use `--version=minor` instead.\n- `--base-branch=origin/main`: Diffs against the `main` branch to find changed packages.\n\nIf you update manually, follow semantic versioning and the [repository's CHANGELOG style](https://github.com/flutter/flutter/blob/master/docs/ecosystem/contributing/README.md#changelog-style).\n","category":"root","tokens":2063}]}