Skip to content

AGENTS.md

Latest commit

聽

History

History
60 lines (43 loc) 路 5.14 KB

AGENTS.md

File metadata and controls

60 lines (43 loc) 路 5.14 KB
Raw

AGENTS

Scope

This file describes repository-wide guidance for the flutter-plugins monorepo. Package-specific guidance may exist deeper in the tree and should be treated as higher-priority context for that subtree.

Detailed guidance for mixin_markdown_widget lives in packages/mixin_markdown_widget/AGENTS.md. Release preparation, publication, and verification guidance for pub packages lives in .agents/skills/flutter-pub-release/SKILL.md.

Repository Overview

  • This repository is a Dart/Flutter monorepo centered around the packages/ directory.
  • Most entries under packages/ are independent Flutter plugins or Dart/Flutter libraries with their own pubspec.yaml, analysis_options.yaml, README.md, tests, and often an example/ app.
  • Public package APIs are generally exposed from a single top-level library file at lib/<package>.dart.
  • The root README.md contains a manually maintained package table; if package status or documentation changes materially, check whether that table should be updated too.
  • Publishing is not automatic for every package. The workflow at .github/workflows/publish.yml uses an explicit allowlist of package names and tag patterns.

Monorepo Working Rules

  • Scope changes to the smallest affected package unless the request explicitly spans multiple packages.
  • Avoid repository-wide refactors unless they are clearly required; packages in this monorepo are mostly independent.
  • Preserve each package's local style, linting, and platform structure instead of imposing a new shared pattern from the root.
  • When changing a package's public API, check the package's top-level export file, README, tests, and example usage together.
  • Prefer package-local validation from the package root rather than running broad workspace-wide commands.
  • Treat generated or platform-host files carefully; do not rewrite native glue code or generated outputs unless the task actually requires it.

Common Layout Expectations

  • packages/<name>/lib/ holds the package's public entrypoint and source tree.
  • packages/<name>/test/ contains focused regression coverage and should be updated when behavior changes.
  • packages/<name>/example/ is the fastest place to verify interactive or visual behavior for UI-heavy packages.
  • Many packages in this repo are desktop-focused plugins, so changes often have platform-specific implications even when the Dart API surface looks small.

Validation Guidance

  • Prefer targeted test runs first, then broader package-level validation if the change affects shared behavior.
  • For Flutter UI packages, pair automated tests with an example/ sanity check when interaction or rendering is involved.
  • Keep unrelated packages untouched unless there is a verified cross-package dependency.

Integration Test Entry Points

  • Each package with integration tests must have exactly one integration test application entry point: example/integration_test/app_test.dart.
  • Register all scenarios through that entry point, with platform dispatch when needed. Put reusable/platform scenarios under integration_test/src/; those files must not define main() or create additional *_test.dart entry points.
  • Every platform target for a package in .github/integration-tests.json must reference the same entry point. Add scenarios to the shared suite instead of adding scenario-specific CI steps or targets.
  • A test_driver/integration_test.dart adapter may run that suite when a platform needs flutter drive; it must not register a separate set of scenarios.

Release Metadata Ownership

  • Keep ordinary feature and fix pull requests focused on the implementation. Do not bump a package version, add the next release section to CHANGELOG.md, or update the workspace lockfile solely to prepare a release.
  • Treat package versions, release changelog sections, and release-related lockfile updates as maintainer-owned release work. Update them together only when the task explicitly asks to prepare or publish a release, following .agents/skills/flutter-pub-release/SKILL.md.
  • Use clear package-scoped commit and pull request titles because release preparation derives candidate entries from commits since the latest package tag. During release preparation, inspect the actual changes and rewrite the final changelog for package users instead of copying contributor wording mechanically.
  • Changes whose explicit purpose is to correct existing release metadata are exempt from this separation.

Commit Message Guidance

  • Use the format <package>: <description> for commits that affect a single package, where <package> is the name of the affected package.
  • describe the change clearly and concisely in the <description> part, focusing on what was changed and why.
  • For commits that affect multiple packages or the repository as a whole, use a more general format
  • prefer a body in the commit message to explain the scope and impact of the change when it is not clear from the title alone.
  • the commit message is intended to generate a changelog entry, so it should be clear and informative for users who may not be familiar with the codebase.