Skip to content

AGENTS.md

Latest commit

 

History

History
85 lines (68 loc) · 3.68 KB

AGENTS.md

File metadata and controls

85 lines (68 loc) · 3.68 KB

Repository Guidelines

Project Structure

analysis_tests/      # Unit tests for the analyzer plugin
lib/
├── src/             # Source code for the package
│   ├── analyzer/    # Analyzer plugin source code
│   ├── async/       # Asynchronous utilities
│   ├── collections/ # Collection
│   ├── core/        # Oref core
│   └── devtools/    # Oref dev tools proto source code
├── devtools.dart    # Dev Tools proto
├── main.dart        # Analyzer Plugin entry
└── oref,dart        # Public APIs
example/             # Is a Flutter app for manual validation and demos
extension/
└── devtools
    ├── app          # Dev Tools Flutter app
    └── config.yaml  # Dev Tools configuration
skills/              # Agent Skills for Oref users (SKILL.md + references)
test/                # Mirrors feature areas with focused unit tests

Build, Test, and Development Commands

  • flutter pub get installs dependencies for the package and the workspace example.
  • extension/devtools/app currently requires Flutter >=3.38.4 to resolve the DevTools extension toolchain.
  • dart analyze runs static analysis using the repo’s flutter_lints rules.
  • dart format . applies standard Dart formatting across the repo.
  • flutter test runs the full unit test suite in test/.
  • cd example && flutter run launches the sample app locally for interactive checks.

Release Process

  • Update versions in pubspec.yaml, extension/devtools/app/pubspec.yaml, extension/devtools/config.yaml, and any version references in README.md.
  • Move Unreleased notes into a new version section in CHANGELOG.md.
  • Rebuild DevTools extension (from extension/devtools/app):
    • flutter pub get
    • dart run devtools_extensions validate --package=../../..
    • dart run devtools_extensions build_and_copy --source=. --dest=../
  • Run tests:
    • flutter test
    • cd analysis_tests && dart test
  • Commit and tag:
    • git commit -m "Release x.y.z"
    • git tag vx.y.z
  • Publish to pub (from repo root):
    • dart pub publish --dry-run
    • dart pub publish --force
  • Create GitHub release:
    • git push origin vx.y.z
    • gh release create vx.y.z --title "vX.Y.Z" --notes-file RELEASE_NOTES.md

Coding Style & Naming Conventions

  • Use 2-space indentation; rely on dart format to enforce style.
  • File names are snake_case.dart; types are UpperCamelCase; methods and variables are lowerCamelCase.
  • Keep public API surface in lib/ and internal helpers in lib/src/, re-exported through lib/oref.dart.

Testing Guidelines

  • Tests use Flutter’s test framework via flutter_test.
  • Name test files with the _test.dart suffix and colocate by feature area.
  • Add regression tests for bug fixes; ensure flutter test passes before opening a PR.

Commit & Pull Request Guidelines

  • Commit messages follow short, imperative phrasing (examples: “Fix missing tracking…”, “Update effect…”).
  • PRs should describe what changed and why, link relevant issues, and note testing performed.
  • Update CHANGELOG.md for user-facing changes or API behavior updates.
  • Include screenshots or GIFs when modifying the example/ UI.

Agent Skills

  • skills/ contains Agent Skills meant for Oref users to install and use.
  • Keep skills focused on Oref usage guidance; store long-form material in references/.

Maintaining Documentation

When making changes to the project (new APIs, architectural changes, updated conventions):

  • AGENTS.md — Update with technical details, architecture, and best practices for AI agents
  • README.md — Update with user-facing documentation (usage, installation, examples) for end users