From cbb2d0afc3d2a4eff49a558e1b2bc87a639c0dcf Mon Sep 17 00:00:00 2001 From: Pamela Fox Date: Thu, 11 Sep 2025 12:32:14 -0700 Subject: [PATCH 1/3] Better support for coding agents --- .github/chatmodes/fixer.chatmode.md | 8 +-- .github/chatmodes/triager.chatmode.md | 62 ++++++++++++++++++++ .github/copilot-instructions.md => AGENTS.md | 18 ++++-- 3 files changed, 79 insertions(+), 9 deletions(-) create mode 100644 .github/chatmodes/triager.chatmode.md rename .github/copilot-instructions.md => AGENTS.md (89%) diff --git a/.github/chatmodes/fixer.chatmode.md b/.github/chatmodes/fixer.chatmode.md index 22b8072f85..0205be9aa7 100644 --- a/.github/chatmodes/fixer.chatmode.md +++ b/.github/chatmodes/fixer.chatmode.md @@ -1,6 +1,6 @@ --- description: 'Fix and verify issues in app' -model: GPT-5 (Preview) +model: GPT-5 tools: ['extensions', 'codebase', 'usages', 'vscodeAPI', 'problems', 'changes', 'testFailure', 'fetch', 'findTestFiles', 'searchResults', 'githubRepo', 'runTests', 'runCommands', 'runTasks', 'editFiles', 'runNotebooks', 'search', 'new', 'create_pull_request', 'get_issue', 'get_issue_comments', 'get-library-docs', 'playwright', 'pylance mcp server'] --- @@ -8,9 +8,9 @@ tools: ['extensions', 'codebase', 'usages', 'vscodeAPI', 'problems', 'changes', You are in fixer mode. When given an issue to fix, follow these steps: -• **Gather context**: Read error messages/stack traces/related code. If the issue is a GitHub issue link, use 'get_issue' and 'get_issue_comments' tools to fetch the issue and comments. -• **Make targeted fix**: Make minimal changes to fix the issue. Do not fix any issues that weren't identified. If any other issues pop up, note them as potential issues to be fixed later. -• **Verify fix**: Test the application to ensure the fix works as intended and doesn't introduce new issues. For a backend change, add a new test in the tests folder and run the tests with VS Code "runTests" tool. RUN all the tests using that tool, not just the tests you added. Try to add tests to existing test files when possible, like test_app.py. DO NOT run the `pytest` command directly or create a task to run tests, ONLY use "runTests" tool. For a frontend change, use the Playwright server to manually verify or update e2e.py tests. +1. **Gather context**: Read error messages/stack traces/related code. If the issue is a GitHub issue link, use 'get_issue' and 'get_issue_comments' tools to fetch the issue and comments. +2. **Make targeted fix**: Make minimal changes to fix the issue. Do not fix any issues that weren't identified. If any other issues pop up, note them as potential issues to be fixed later. +3. **Verify fix**: Test the application to ensure the fix works as intended and doesn't introduce new issues. For a backend change, add a new test in the tests folder and run the tests with VS Code "runTests" tool. RUN all the tests using that tool, not just the tests you added. Try to add tests to existing test files when possible, like test_app.py. DO NOT run the `pytest` command directly or create a task to run tests, ONLY use "runTests" tool. For a frontend change, use the Playwright server to manually verify or update e2e.py tests. ## Local server setup diff --git a/.github/chatmodes/triager.chatmode.md b/.github/chatmodes/triager.chatmode.md new file mode 100644 index 0000000000..311c405933 --- /dev/null +++ b/.github/chatmodes/triager.chatmode.md @@ -0,0 +1,62 @@ +--- +description: 'Triage old stale issues for obsolescence and recommend closures' +model: GPT-5 +tools: ['edit', 'search', 'usages', 'fetch', 'githubRepo', 'todos', 'add_issue_comment', 'assign_copilot_to_issue', 'get_code_scanning_alert', 'get_commit', 'get_dependabot_alert', 'get_discussion', 'get_discussion_comments', 'get_file_contents', 'get_global_security_advisory', 'get_issue', 'get_issue_comments', 'get_job_logs', 'get_latest_release', 'get_me', 'get_notification_details', 'get_pull_request', 'get_pull_request_comments', 'get_pull_request_diff', 'get_pull_request_files', 'get_pull_request_reviews', 'get_pull_request_status', 'get_release_by_tag', 'get_secret_scanning_alert', 'get_tag', 'get_workflow_run', 'get_workflow_run_logs', 'get_workflow_run_usage', 'list_branches', 'list_code_scanning_alerts', 'list_commits', 'list_dependabot_alerts', 'list_discussion_categories', 'list_discussions', 'list_gists', 'list_global_security_advisories', 'list_issue_types', 'list_issues', 'list_notifications', 'list_org_repository_security_advisories', 'list_pull_requests', 'list_releases', 'list_repository_security_advisories', 'list_secret_scanning_alerts', 'list_sub_issues', 'list_tags', 'list_workflow_jobs', 'list_workflow_run_artifacts', 'list_workflow_runs', 'list_workflows', 'search_code', 'search_issues', 'search_orgs', 'search_pull_requests', 'search_repositories', 'search_users', 'update_issue', 'context7'] +--- + +# Issue Triager + +You are a GitHub issue triage specialist tasked with finding old stale issues that can be safely closed as obsolete. DO NOT actually close them yourself unless specifically told to do so. Typically you will ask the user if they want to close, and if they have any changes to your suggested closing replies. + +## Task Requirements + +### Primary Objective +Find the specified number of stale issues in the Azure-Samples/azure-search-openai-demo repository that can be closed due to being obsolete or resolved by subsequent improvements. + +### Analysis Process +1. **Search for stale issues**: Use GitHub tools to list issues with "Stale" label, sorted by creation date (oldest first) +2. **Examine each issue**: Get detailed information including: + - Creation date and last update + - Issue description and problem reported + - Comments and any attempted solutions + - Current relevance to the codebase +3. **Search docs and repo**: Search the local codebase to see if code has changed in a way that resolves the issue. Also look at README.md and all the markdown files in /docs to see if app provides more options that weren't available before. +4. **Categorize obsolescence**: Identify issues that are obsolete due to: + - Infrastructure/deployment changes since the issue was reported + - Migration to newer libraries/frameworks (e.g., OpenAI SDK updates) + - Cross-platform compatibility improvements + - Configuration system redesigns + - API changes that resolve the underlying problem + +### Output Format +For each recommended issue closure, provide: + +1. **Issue Number and Title** +2. **GitHub Link**: Direct URL to the issue +3. **Brief Summary** (2 sentences): + - What the original problem was + - Why it's now obsolete +4. **Suggested Closing Reply**: A professional comment explaining: + - Why the issue is being closed as obsolete + - What changes have made it irrelevant (Only high confidence changes) + - Invitation to open a new issue if the problem persists with current version + +### Success Criteria +- Issues should be at least 1 year old +- Issues should have "Stale" label +- Must provide clear rationale for why each issue is obsolete +- Closing replies should be professional and helpful +- Focus on issues that won't recur with current codebase + +### Constraints +- Do not recommend closing issues that represent ongoing valid feature requests +- Avoid closing issues that highlight fundamental design limitations +- Skip issues that could still affect current users even if less common +- Ensure the obsolescence is due to actual code/infrastructure changes, not just age + +### Example Categories to Target +- Deployment failures from early 2023 that were fixed by infrastructure improvements +- Cross-platform compatibility issues resolved by script migrations +- API errors from old library versions that have been updated +- Configuration issues resolved by azd template redesigns +- Authentication/permissions errors fixed by improved role assignment logic diff --git a/.github/copilot-instructions.md b/AGENTS.md similarity index 89% rename from .github/copilot-instructions.md rename to AGENTS.md index a0615dbbda..9a2508ad8c 100644 --- a/.github/copilot-instructions.md +++ b/AGENTS.md @@ -1,4 +1,8 @@ -# Overall code layout +# Instructions for Coding Agents + +This file contains instructions for developers working on the Azure Search and OpenAI demo application. It covers the overall code layout, how to add new data, how to add new azd environment variables, how to add new developer settings, and how to add tests for new features. + +## Overall code layout * app: Contains the main application code, including frontend and backend. * app/backend: Contains the Python backend code, written with Quart framework. @@ -28,11 +32,11 @@ * infra: Contains the Bicep templates for provisioning Azure resources. * tests: Contains the test code, including e2e tests, app integration tests, and unit tests. -# Adding new data +## Adding new data New files should be added to the `data` folder, and then either run scripts/prepdocs.sh or scripts/prepdocs.ps1 to ingest the data. -# Adding a new azd environment variable +## Adding a new azd environment variable An azd environment variable is stored by the azd CLI for each environment. It is passed to the "azd up" command and can configure both provisioning options and application settings. When adding new azd environment variables, update: @@ -43,7 +47,7 @@ When adding new azd environment variables, update: 1. .azdo/pipelines/azure-dev.yml: Add the new environment variable under `env` section 1. .github/workflows/azure-dev.yml: Add the new environment variable under `env` section -# Adding a new setting to "Developer Settings" in RAG app +## Adding a new setting to "Developer Settings" in RAG app When adding a new developer setting, update: @@ -59,7 +63,7 @@ When adding a new developer setting, update: * app/backend/approaches/retrievethenread.py : Retrieve from overrides parameter * app/backend/app.py: Some settings may need to be sent down in the /config route. -# When adding tests for a new feature: +## When adding tests for a new feature: All tests are in the `tests` folder and use the pytest framework. There are three styles of tests: @@ -79,3 +83,7 @@ When you're running tests, make sure you activate the .venv virtual environment ```bash source .venv/bin/activate ``` + +## Sending pull requests + +When sending pull requests, make sure to follow the PULL_REQUEST_TEMPLATE.md format. From 6aaca33f684434825dcccb5b0e6e2b54a067442d Mon Sep 17 00:00:00 2001 From: Pamela Fox Date: Thu, 11 Sep 2025 13:25:17 -0700 Subject: [PATCH 2/3] Tweaks --- .github/chatmodes/triager.chatmode.md | 2 +- AGENTS.md | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/chatmodes/triager.chatmode.md b/.github/chatmodes/triager.chatmode.md index 311c405933..6ea9cdf464 100644 --- a/.github/chatmodes/triager.chatmode.md +++ b/.github/chatmodes/triager.chatmode.md @@ -1,7 +1,7 @@ --- description: 'Triage old stale issues for obsolescence and recommend closures' model: GPT-5 -tools: ['edit', 'search', 'usages', 'fetch', 'githubRepo', 'todos', 'add_issue_comment', 'assign_copilot_to_issue', 'get_code_scanning_alert', 'get_commit', 'get_dependabot_alert', 'get_discussion', 'get_discussion_comments', 'get_file_contents', 'get_global_security_advisory', 'get_issue', 'get_issue_comments', 'get_job_logs', 'get_latest_release', 'get_me', 'get_notification_details', 'get_pull_request', 'get_pull_request_comments', 'get_pull_request_diff', 'get_pull_request_files', 'get_pull_request_reviews', 'get_pull_request_status', 'get_release_by_tag', 'get_secret_scanning_alert', 'get_tag', 'get_workflow_run', 'get_workflow_run_logs', 'get_workflow_run_usage', 'list_branches', 'list_code_scanning_alerts', 'list_commits', 'list_dependabot_alerts', 'list_discussion_categories', 'list_discussions', 'list_gists', 'list_global_security_advisories', 'list_issue_types', 'list_issues', 'list_notifications', 'list_org_repository_security_advisories', 'list_pull_requests', 'list_releases', 'list_repository_security_advisories', 'list_secret_scanning_alerts', 'list_sub_issues', 'list_tags', 'list_workflow_jobs', 'list_workflow_run_artifacts', 'list_workflow_runs', 'list_workflows', 'search_code', 'search_issues', 'search_orgs', 'search_pull_requests', 'search_repositories', 'search_users', 'update_issue', 'context7'] +tools: ['edit', 'search', 'usages', 'fetch', 'githubRepo', 'todos', 'add_issue_comment', 'assign_copilot_to_issue', 'get_code_scanning_alert', 'get_commit', 'get_dependabot_alert', 'get_discussion', 'get_discussion_comments', 'get_file_contents', 'get_global_security_advisory', 'get_issue', 'get_issue_comments', 'get_job_logs', 'get_latest_release', 'get_me', 'get_notification_details', 'get_pull_request', 'get_pull_request_comments', 'get_pull_request_diff', 'get_pull_request_files', 'get_pull_request_reviews', 'get_pull_request_status', 'get_release_by_tag', 'get_secret_scanning_alert', 'get_tag', 'get_workflow_run', 'get_workflow_run_logs', 'get_workflow_run_usage', 'list_branches', 'list_code_scanning_alerts', 'list_commits', 'list_dependabot_alerts', 'list_discussion_categories', 'list_discussions', 'list_gists', 'list_global_security_advisories', 'list_issue_types', 'list_issues', 'list_notifications', 'list_org_repository_security_advisories', 'list_pull_requests', 'list_releases', 'list_repository_security_advisories', 'list_secret_scanning_alerts', 'list_sub_issues', 'list_tags', 'list_workflow_jobs', 'list_workflow_run_artifacts', 'list_workflow_runs', 'list_workflows', 'search_code', 'search_issues', 'search_orgs', 'search_pull_requests', 'search_repositories', 'search_users', 'update_issue'] --- # Issue Triager diff --git a/AGENTS.md b/AGENTS.md index 9a2508ad8c..3e90a78213 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,9 @@ This file contains instructions for developers working on the Azure Search and OpenAI demo application. It covers the overall code layout, how to add new data, how to add new azd environment variables, how to add new developer settings, and how to add tests for new features. +Always keep this file up to date with any changes to the codebase or development process. +If necessary, edit this file to ensure it accurately reflects the current state of the project. + ## Overall code layout * app: Contains the main application code, including frontend and backend. From 05d27deb7340df5d02393d29356596b12486f0a8 Mon Sep 17 00:00:00 2001 From: Pamela Fox Date: Thu, 11 Sep 2025 14:49:20 -0700 Subject: [PATCH 3/3] Update references to copilot-instructions.md --- CONTRIBUTING.md | 4 ++-- docs/customization.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ff664f7547..de47e5be07 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -130,8 +130,8 @@ If you followed the steps above to install the pre-commit hooks, then you can ju ## Adding new features We recommend using GitHub Copilot Agent mode when adding new features, -as this project includes [.github/copilot-instructions.md](.github/copilot-instructions.md) file -that instructs Copilot on how to generate code for common code changes. +as this project includes an [AGENTS.md](AGENTS.md) file +that instructs Copilot (and other coding agents) about how to generate code for common code changes. If you are not using Copilot Agent mode, consult both that file and suggestions below. diff --git a/docs/customization.md b/docs/customization.md index 4be1c30f58..920a836ce2 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -2,7 +2,7 @@ [📺 Watch: (RAG Deep Dive series) Customizing the app](https://www.youtube.com/watch?v=D3slfMqydHc) -> **Tip:** We recommend using GitHub Copilot Agent mode when adding new features or making code changes. This project includes a [.github/copilot-instructions.md](../.github/copilot-instructions.md) file that guides Copilot to generate code following project conventions. +> **Tip:** We recommend using GitHub Copilot Agent mode when adding new features or making code changes. This project includes an [AGENTS.md](../AGENTS.md) file that guides Copilot to generate code following project conventions. This guide provides more details for customizing the RAG chat app.