From ccfa4f86318f031249c690673b57cb93b04f25ca Mon Sep 17 00:00:00 2001 From: Pamela Fox Date: Mon, 4 Aug 2025 11:40:19 -0700 Subject: [PATCH 1/5] Add chat modes and prompts --- .github/chatmodes/debug.chatmode.md | 27 ++++++++++++ .github/prompts/stalefinder.prompt.md | 60 +++++++++++++++++++++++++++ app/backend/Dockerfile | 2 +- 3 files changed, 88 insertions(+), 1 deletion(-) create mode 100644 .github/chatmodes/debug.chatmode.md create mode 100644 .github/prompts/stalefinder.prompt.md diff --git a/.github/chatmodes/debug.chatmode.md b/.github/chatmodes/debug.chatmode.md new file mode 100644 index 0000000000..2e022bb077 --- /dev/null +++ b/.github/chatmodes/debug.chatmode.md @@ -0,0 +1,27 @@ +--- +description: 'Debug application to find and fix a bug' +model: Claude Sonnet 4 +tools: ['codebase', 'usages', 'vscodeAPI', 'problems', 'changes', 'testFailure', 'terminalSelection', 'terminalLastCommand', 'fetch', 'findTestFiles', 'searchResults', 'githubRepo', 'extensions', 'runTests', 'editFiles', 'runNotebooks', 'search', 'new', 'runCommands', 'get_issue', 'get_issue_comments', 'pylance mcp server', 'get-library-docs', 'Microsoft Docs', 'playwright'] +--- + +# Debug Mode Instructions + +You are in debug mode. Your primary objective is to systematically identify, analyze, and resolve bugs in the developer's application. Follow this structured debugging process: + +## Debugging process + +• **Reproduce first**: Try to reproduce the bug before making changes - run the app with start script, test app with Playwright MCP, capture exact error messages and steps +• **Gather context**: Read error messages/stack traces, examine recent changes, identify expected vs actual behavior +• **Root cause analysis**: Trace execution path, check for common issues (null refs, race conditions), use search tools to understand component interactions +• **Targeted fix**: Make minimal changes addressing root cause, follow existing patterns, consider edge cases +• **Verify thoroughly**: Run tests to confirm fix, check for regressions, test edge cases +• **Document**: Summarize what was fixed, explain root cause, suggest preventive measures + +## Local server setup: + +- To run the application, run the "Start app" task +- To interact with the application, use the Playwright MCP server +- If you change the JS, rebuild and restart the server by ending the task and running the "Start app" task again. +- Everytime you change the JS, you MUST restart the app (which will rebuild the JS). Otherwise, the changes will not appear. +- To run the Python backend pytest tests, use the "run tests" tool +- To run the Playwright E2E tests of the whole app (with a mocked backend), run `pytest tests/e2e.py --tracing=retain-on-failure`. diff --git a/.github/prompts/stalefinder.prompt.md b/.github/prompts/stalefinder.prompt.md new file mode 100644 index 0000000000..b493e5edd8 --- /dev/null +++ b/.github/prompts/stalefinder.prompt.md @@ -0,0 +1,60 @@ +--- +mode: agent +--- + +# Stale Issue Finder and Analyzer + +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/app/backend/Dockerfile b/app/backend/Dockerfile index a84bd6e0b7..046585426c 100644 --- a/app/backend/Dockerfile +++ b/app/backend/Dockerfile @@ -1,4 +1,4 @@ -FROM python:3.11-bullseye +FROM python:3.12-alpine WORKDIR /app From b5383766293c7e5a9adccd831b0fd417ab739c77 Mon Sep 17 00:00:00 2001 From: Pamela Fox Date: Mon, 11 Aug 2025 15:07:58 -0700 Subject: [PATCH 2/5] Fix tasks to work with chat mode --- .github/chatmodes/debug.chatmode.md | 29 ++++++++----- .vscode/tasks.json | 65 +++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+), 10 deletions(-) diff --git a/.github/chatmodes/debug.chatmode.md b/.github/chatmodes/debug.chatmode.md index 2e022bb077..cb02ceb03f 100644 --- a/.github/chatmodes/debug.chatmode.md +++ b/.github/chatmodes/debug.chatmode.md @@ -1,7 +1,7 @@ --- description: 'Debug application to find and fix a bug' -model: Claude Sonnet 4 -tools: ['codebase', 'usages', 'vscodeAPI', 'problems', 'changes', 'testFailure', 'terminalSelection', 'terminalLastCommand', 'fetch', 'findTestFiles', 'searchResults', 'githubRepo', 'extensions', 'runTests', 'editFiles', 'runNotebooks', 'search', 'new', 'runCommands', 'get_issue', 'get_issue_comments', 'pylance mcp server', 'get-library-docs', 'Microsoft Docs', 'playwright'] +model: GPT-5 (Preview) +tools: ['extensions', 'codebase', 'usages', 'vscodeAPI', 'problems', 'changes', 'testFailure', 'terminalSelection', 'terminalLastCommand', 'fetch', 'findTestFiles', 'searchResults', 'githubRepo', 'todos', 'runTests', 'runCommands', 'runTasks', 'editFiles', 'runNotebooks', 'search', 'new', 'Microsoft Docs', 'get_issue', 'get_issue_comments', 'get-library-docs', 'playwright', 'pylance mcp server'] --- # Debug Mode Instructions @@ -10,18 +10,27 @@ You are in debug mode. Your primary objective is to systematically identify, ana ## Debugging process -• **Reproduce first**: Try to reproduce the bug before making changes - run the app with start script, test app with Playwright MCP, capture exact error messages and steps -• **Gather context**: Read error messages/stack traces, examine recent changes, identify expected vs actual behavior -• **Root cause analysis**: Trace execution path, check for common issues (null refs, race conditions), use search tools to understand component interactions +• **Gather context**: Read error messages/stack traces, examine recent changes, identify expected vs actual behavior. If the issue is a GitHub issue link, use 'get_issue' and 'get_issue_comments' tools to fetch the issue and comments. +• **Root cause analysis**: Trace execution path, check for common issues, use search tools to understand component interactions • **Targeted fix**: Make minimal changes addressing root cause, follow existing patterns, consider edge cases • **Verify thoroughly**: Run tests to confirm fix, check for regressions, test edge cases -• **Document**: Summarize what was fixed, explain root cause, suggest preventive measures +• **Document**: Summarize what was fixed, explain root cause, suggest preventive measures. Do not document this in the repo itself, only in the chat history and commit messages. -## Local server setup: +## Local server setup -- To run the application, run the "Start app" task +You MUST check task output readiness before debugging, testing, or declaring work complete. + +- Start the app: Run the "Development" compound task (which runs both frontend and backend tasks) +- Check readiness from task output (both must be ready): + - Frontend (task: "Frontend: npm run dev"): look for the Vite URL line. Either of these indicates ready: + - "Local: http://127.0.0.1:..." or "➜ Local: http://127.0.0.1:..." + - Backend (task: "Backend: quart run"): wait for Hypercorn to bind. Ready when you see: + - "INFO:hypercorn.error:Running on http://127.0.0.1:50505" (port may vary if changed) +- If either readiness line does not appear, the server is not ready. Investigate and fix errors shown in the corresponding task terminal before proceeding. +- Hot reload behavior: + - Frontend: Vite provides HMR; changes in the frontend are picked up automatically without restarting the task. + - Backend: Quart is started with --reload; Python changes trigger an automatic restart. + - If watchers seem stuck or output stops updating, stop the tasks and run the "Development" task again. - To interact with the application, use the Playwright MCP server -- If you change the JS, rebuild and restart the server by ending the task and running the "Start app" task again. -- Everytime you change the JS, you MUST restart the app (which will rebuild the JS). Otherwise, the changes will not appear. - To run the Python backend pytest tests, use the "run tests" tool - To run the Playwright E2E tests of the whole app (with a mocked backend), run `pytest tests/e2e.py --tracing=retain-on-failure`. diff --git a/.vscode/tasks.json b/.vscode/tasks.json index d4fdd8a2fe..a195a5ffdb 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -15,6 +15,71 @@ "cwd": "${workspaceFolder}/app" }, "problemMatcher": [] + }, + { + "label": "Development", + "dependsOn": [ + "Frontend: npm run dev", + "Backend: quart run" + ], + "group": { + "kind": "build", + "isDefault": true + } + }, + { + "label": "Frontend: npm run dev", + "type": "npm", + "script": "dev", + "isBackground": true, + "options": { + "cwd": "${workspaceFolder}/app/frontend" + }, + "presentation": { + "reveal": "always", + "group": "buildWatchers", + "panel": "dedicated", + "clear": false + }, + "problemMatcher": { + "pattern": { + "regexp": "" + }, + "background": { + "activeOnStart": true, + "beginsPattern": ".*VITE v.*", + "endsPattern": ".*(?:➜\\s*)?Local:\\s+https?://.*" + } + } + }, + { + "label": "Backend: quart run", + "type": "shell", + "command": "${workspaceFolder}/.venv/bin/python", + "args": ["-m", "quart", "run", "--reload", "-p", "50505"], + "options": { + "cwd": "${workspaceFolder}/app/backend", + "env": { + "QUART_APP": "main:app", + "QUART_ENV": "development", + "QUART_DEBUG": "0", + "LOADING_MODE_FOR_AZD_ENV_VARS": "override" + } + }, + "isBackground": true, + "presentation": { + "reveal": "always", + "group": "buildWatchers", + "panel": "dedicated" + }, + "problemMatcher": { + "pattern": { "regexp": "" }, + "background": { + "activeOnStart": true, + "beginsPattern": ".*Serving Quart app.*", + "endsPattern": ".*hypercorn.*Running on http://.*" + } + } } ] } From 6baf43b1fea7e61824f8396f2552b097efc46229 Mon Sep 17 00:00:00 2001 From: Pamela Fox Date: Mon, 11 Aug 2025 15:10:18 -0700 Subject: [PATCH 3/5] Remove unrelated changes --- .github/prompts/stalefinder.prompt.md | 60 --------------------------- app/backend/Dockerfile | 2 +- 2 files changed, 1 insertion(+), 61 deletions(-) delete mode 100644 .github/prompts/stalefinder.prompt.md diff --git a/.github/prompts/stalefinder.prompt.md b/.github/prompts/stalefinder.prompt.md deleted file mode 100644 index b493e5edd8..0000000000 --- a/.github/prompts/stalefinder.prompt.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -mode: agent ---- - -# Stale Issue Finder and Analyzer - -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/app/backend/Dockerfile b/app/backend/Dockerfile index 046585426c..a84bd6e0b7 100644 --- a/app/backend/Dockerfile +++ b/app/backend/Dockerfile @@ -1,4 +1,4 @@ -FROM python:3.12-alpine +FROM python:3.11-bullseye WORKDIR /app From 543730b74ce6c0a7409464b516b02cdc360ad1de Mon Sep 17 00:00:00 2001 From: Pamela Fox Date: Mon, 11 Aug 2025 15:37:29 -0700 Subject: [PATCH 4/5] Update docs about local dev --- docs/localdev.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/docs/localdev.md b/docs/localdev.md index b72199c029..35c40dc045 100644 --- a/docs/localdev.md +++ b/docs/localdev.md @@ -4,6 +4,8 @@ After deploying the app to Azure, you may want to continue development locally. * [Running development server from the command line](#running-development-server-from-the-command-line) * [Hot reloading frontend and backend files](#hot-reloading-frontend-and-backend-files) +* [Using VS Code "Development" task](#using-vs-code-development-task) +* [Using Copilot Chat Debug Mode](#using-copilot-chat-debug-mode) * [Using VS Code "Run and Debug"](#using-vs-code-run-and-debug) * [Using a local OpenAI-compatible API](#using-a-local-openai-compatible-api) * [Using Ollama server](#using-ollama-server) @@ -64,6 +66,56 @@ Navigate to the URL shown in the terminal (in this case, `http://localhost:5173/ Then, whenever you make changes to frontend files, the changes will be automatically reloaded, without any browser refresh needed. +Alternatively, you can start both servers with hot reloading by using the VS Code "Development" task. See [Using VS Code "Development" task](#using-vs-code-development-task). + +## Using VS Code "Development" task + +If you prefer VS Code tasks for hot reloading both servers at once, use the "Development" task defined in `.vscode/tasks.json`. + +How to run it: + +* Run Build Task (Shift+Cmd+B) to start the default build task, which is "Development". +* Or open the Command Palette (Shift+Cmd+P) and run: "Tasks: Run Task" -> "Development". + +What it does: + +* Starts two background tasks in dedicated panels: + * "Frontend: npm run dev" from `app/frontend` (Vite HMR for instant frontend updates) + * "Backend: quart run" from `app/backend` (Quart with `--reload` for backend auto-restarts) + +Readiness indicators: + +* Frontend is ready when Vite prints a Local URL, for example: `Local: http://localhost:5173/`. +* Backend is ready when Hypercorn reports: `Running on http://127.0.0.1:50505` (port may vary). + +Tips: + +* To stop both, run: "Tasks: Terminate Task" and pick the running tasks. +* If watchers stall, terminate and run "Development" again. +* Frontend changes apply via HMR; backend Python changes auto-reload. No manual restart needed. + +## Using Copilot Chat Debug Mode + +You can use GitHub Copilot Chat with a custom "debug" mode to streamline troubleshooting in this repo. + +Prerequisites: + +* VS Code 1.101+ (custom chat modes are in preview) +* Access to GitHub Copilot and Copilot Chat +* Playwright MCP server and GitHub MCP server (optional) + +To learn more about the chat modes feature, read [VS Code docs for Chat modes](https://code.visualstudio.com/docs/copilot/chat/chat-modes). + +To use the debug mode: + +* Open the Chat view. +* Use the chat mode dropdown at the top of the Chat view to select the "debug" mode. +* Start chatting in that mode; the instructions and tools from the repo file will be applied automatically. +* The mode will use the tasks from .vscode/tasks.json to run the frontend and backend server, and should be able to read any errors in the output. +* The mode may also use tools from the Playwright MCP server and GitHub MCP server, if those servers are installed in your VS Code. + +Notably, this mode will not actually use a breakpoint-based debugger. Read on to learn how to use breakpoints while debugging the Python code. + ## Using VS Code "Run and Debug" This project includes configurations defined in `.vscode/launch.json` that allow you to run and debug the app directly from VS Code: From 173729deda49cf97397493afede745e2b40792f5 Mon Sep 17 00:00:00 2001 From: Pamela Fox Date: Mon, 11 Aug 2025 16:06:04 -0700 Subject: [PATCH 5/5] Add Windows command --- .vscode/tasks.json | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.vscode/tasks.json b/.vscode/tasks.json index a195a5ffdb..f08aeb5cff 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -56,6 +56,9 @@ "label": "Backend: quart run", "type": "shell", "command": "${workspaceFolder}/.venv/bin/python", + "windows": { + "command": "${workspaceFolder}\\.venv\\Scripts\\python.exe" + }, "args": ["-m", "quart", "run", "--reload", "-p", "50505"], "options": { "cwd": "${workspaceFolder}/app/backend",