Add Copilot repository instructions for agent onboarding

[Copilot]

Provides comprehensive onboarding instructions for coding agents working with this Flutter package repository.

Changes

Created .github/copilot-instructions.md with:

• Repository summary - Flutter package structure, directories (lib/, example/, test/), and key files
• Environment setup - Flutter SDK installation, dependency management for root and example directories
• Build & validation - Commands for formatting (flutter format --set-exit-if-changed), analysis (flutter analyze), testing (flutter test), and package validation (flutter pub publish --dry-run)
• CI workflow - GitHub Actions pipeline steps that agents should replicate locally
• Architecture notes - Public API change requirements (update README.md and CHANGELOG.md)
• SDK requirements - Flutter 3.24.0+, Dart SDK 3.5.0+ per pubspec.yaml and CI configuration
• Pre-PR checklist - Complete validation steps including dependency installation in both directories
• Search policy - When to trust instructions vs. search repository structure

Agents can now bootstrap the environment and validate changes consistently without manual guidance.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://storage.googleapis.com/flutter_infra_release/flutter/b5990e5ccc5e325fd24f0746e7d6689bbebc7c65/dart-sdk-linux-x64.zip
  • Triggering command: /usr/bin/curl curl --retry 3 --continue-at - --location --output /tmp/flutter/bin/cache/dart-sdk-linux-x64.zip REDACTED (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Copilot Repository Instructions

These instructions onboard this repository for coding agents. They describe the repository layout, required tools, build and validation steps, and how to reliably work with the project. These instructions are not task-specific and should be reused for all future changes.

1. Repository Summary

This repository contains a Flutter package that provides an enhanced dropdown widget usable in Flutter applications. The package is structured as a standard Dart/Flutter package with a runnable example app demonstrating usage. The codebase is small, uses only Dart, and targets Flutter’s stable toolchain.

2. High-Level Repository Information

Type: Flutter package

Languages: Dart

Main directories:

lib/ — package source code

example/ — runnable demo app

test/ — package tests

.github/workflows/ — CI scripts

Key files: pubspec.yaml, README.md, CHANGELOG.md

Before making any changes, always inspect pubspec.yaml for SDK constraints, dependencies, and package metadata.

3. Environment & Bootstrap Instructions

Always perform the following steps when starting work or after switching branches:

Ensure a Flutter SDK (stable channel) is installed and available in PATH.

Verify the SDK version:

flutter --version

Install all package dependencies:

flutter pub get

When working inside the example/ folder, run flutter pub get there as well.

4. Build, Lint, and Test Instructions
   A. Formatting (must pass before PR)
   flutter format --set-exit-if-changed .

B. Static Analysis
flutter analyze

C. Run Tests
flutter test

D. Validate Package for Publishing
flutter pub publish --dry-run

This checks for metadata issues, missing files, and pubspec problems.

E. Run the Example App

To validate runtime behavior of the widget:

cd example
flutter pub get
flutter run -d

Use flutter devices to list available devices.
If none exist, start an emulator (flutter emulators) or connect a physical device.

5. Continuous Integration

The repository includes GitHub workflows under .github/workflows/.
These typically perform:

flutter pub get

flutter analyze

flutter test

Agents should replicate these steps locally before proposing changes.
Any change that fails CI should be corrected before issuing a pull request.

6. Project Layout & Architectural Notes

Library source: All production code is under lib/. Any feature or bugfix must be implemented here.

Public API: Changing widgets, constructors, exported types, or behavior requires updating both README.md and CHANGELOG.md.

Example app: Located in example/. Use this to manually test UI interactions and dropdown behavior.

Tests: Located in test/. Add or update tests when modifying behavior.

Configuration files:

pubspec.yaml — package metadata, dependencies, SDK constraints

analysis_options.yaml (if present) — static analysis rules

GitHub workflow files — define CI pipeline

7. Common Issues & Required Precautions

Always run flutter pub get in both project root and example/ before builds.

SDK mismatches: If dependency resolution fails, adjust environment Flutter version according to pubspec.yaml constraints.

Running example app: Requires an emulator or device; flutter run fails if none are available.

Formatting and analysis errors: Must be fixed before submitting changes.

Behavior changes: If modifying dropdown behavior or object serialization, confirm that the example app still works correctly.

8. Pre-PR Validation Checklist

Agents should validate all of the following before creating a pull request:

flutter pub get runs without errors.

Code formatting passes: flutter format --set-exit-if-changed .

Static analysis passes: flutter analyze

All tests pass: flutter test

Example app runs successfully and demonstrates correct widget behavior.

Package passes publishing checks: flutter pub publish --dry-run

If public API changed: update README.md and CHANGELOG.md.

9. Trust & Search Policy

Agents should first trust these instructions for all build, test, and run steps.
Search the repository structure only when:

A command produces an unexpected or undocumented error, or

A referenced file is missing or differs significantly.

When searching, examine files in this priority order:
pubspec.yaml → .github/workflows/ → lib/ → example/ → test/ → root-level docs.

This concludes the repository’s onboarding instructions.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.