From ce2316fb10541d047d2adb565c001c60b8a8ab77 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 4 Nov 2025 06:22:24 +0000 Subject: [PATCH] Add agent instructions for screenshot capture using Playwright Co-authored-by: stnguyen90 <1477010+stnguyen90@users.noreply.github.com> --- .github/PULL_REQUEST_TEMPLATE.md | 16 +- .github/agents/README.md | 55 +++++++ .github/agents/code-change-agent.md | 205 +++++++++++++++++++++++++ .github/agents/screenshot-guide.md | 226 ++++++++++++++++++++++++++++ .github/workflows/issue-triage.md | 1 + 5 files changed, 502 insertions(+), 1 deletion(-) create mode 100644 .github/agents/README.md create mode 100644 .github/agents/code-change-agent.md create mode 100644 .github/agents/screenshot-guide.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index ab59c97ff7..b2061b1f5e 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -15,7 +15,21 @@ Happy contributing! ## Test Plan -(Write your test plan here. If you changed any code, please provide us with clear instructions on how you verified your changes work. Screenshots may also be helpful.) +(Write your test plan here. If you changed any code, please provide us with clear instructions on how you verified your changes work.) + +## Screenshots + +**Required for UI changes**: If this PR includes visual/UI changes, please include before/after screenshots. +See [screenshot guide](.github/agents/screenshot-guide.md) for instructions on using Playwright to capture screenshots. + +- [ ] Screenshots included (or not applicable) + + ## Related PRs and Issues diff --git a/.github/agents/README.md b/.github/agents/README.md new file mode 100644 index 0000000000..5a135e6b58 --- /dev/null +++ b/.github/agents/README.md @@ -0,0 +1,55 @@ +# Agent Instructions + +This directory contains instruction files for various automated agents that work with the Appwrite repository. + +## Purpose + +These instruction files provide standardized guidelines for: +- AI-powered coding agents (e.g., GitHub Copilot) +- Automated workflow agents +- Code review assistants +- Issue triage bots + +## Available Instructions + +### code-change-agent.md +Instructions for agents that make code changes and create pull requests. Includes: +- Code change best practices +- Testing requirements +- **Screenshot capture guidelines using Playwright** +- PR submission standards + +## Using These Instructions + +### For Human Contributors +While these instructions are primarily for automated agents, human contributors may find them useful as: +- Guidelines for creating high-quality PRs +- Standards for documenting UI changes +- Best practices for testing + +### For Agent Developers +When building or configuring automated agents for this repository: +1. Review the relevant instruction file for the agent's purpose +2. Ensure the agent follows the guidelines, especially screenshot requirements for UI changes +3. Test the agent's behavior against these standards before deployment + +## Screenshot Requirements + +**All agents making UI changes MUST capture screenshots** to document visual modifications. See `code-change-agent.md` for detailed instructions on: +- When to take screenshots +- How to use Playwright for screenshot capture +- How to include screenshots in PRs + +## Contributing + +To update or add agent instructions: +1. Create or modify the appropriate `.md` file in this directory +2. Follow the existing format and structure +3. Ensure instructions are clear, actionable, and testable +4. Submit a PR with your changes + +## Related Files + +- `.github/workflows/issue-triage.md` - Agentic workflow for issue triage +- `.github/PULL_REQUEST_TEMPLATE.md` - PR template that all PRs should follow +- `CONTRIBUTING.md` - General contributing guidelines diff --git a/.github/agents/code-change-agent.md b/.github/agents/code-change-agent.md new file mode 100644 index 0000000000..293f56092d --- /dev/null +++ b/.github/agents/code-change-agent.md @@ -0,0 +1,205 @@ +# Code Change Agent Instructions + +## Overview +This document provides instructions for agents that make code changes to the Appwrite repository. These instructions ensure consistency and quality across automated code contributions. + +## General Guidelines + +### Code Changes +1. Make minimal, focused changes that address the specific issue or requirement +2. Follow the existing code style and conventions in the repository +3. Ensure all changes are properly tested +4. Update documentation when changing public APIs or adding new features + +### Testing Requirements +1. Run existing tests to ensure no regressions +2. Add new tests for new functionality +3. Ensure all tests pass before creating a PR + +## Screenshot Requirements for UI Changes + +**IMPORTANT**: When making changes that affect the user interface or visual output, you MUST capture screenshots to document the changes. + +### When to Take Screenshots +Take screenshots in the following scenarios: +- Changes to web UI components, layouts, or styles +- Modifications to console output or terminal displays +- Updates to dashboards, admin panels, or user-facing interfaces +- Changes that affect visual rendering or appearance +- New UI features or components + +### How to Take Screenshots Using Playwright + +1. **Install Playwright** (if not already available): + ```bash + npm install -D @playwright/test + npx playwright install + ``` + +2. **Create a screenshot script** in `/tmp/take-screenshots.js`: + ```javascript + const { chromium } = require('playwright'); + + (async () => { + const browser = await chromium.launch(); + const page = await browser.newPage(); + + // Navigate to the changed UI + await page.goto('http://localhost:PORT/YOUR-PATH'); + + // Wait for the page to fully load + await page.waitForLoadState('networkidle'); + + // Take screenshot + await page.screenshot({ + path: 'screenshot-before.png', + fullPage: true + }); + + await browser.close(); + })(); + ``` + +3. **Take "before" and "after" screenshots**: + - Take a screenshot of the UI BEFORE your changes (if possible) + - Make your code changes + - Take a screenshot of the UI AFTER your changes + - Save screenshots with descriptive names like: + - `ui-change-before.png` + - `ui-change-after.png` + - `feature-name-screenshot.png` + +4. **Alternative: Use Playwright Test**: + ```javascript + const { test, expect } = require('@playwright/test'); + + test('capture UI changes', async ({ page }) => { + await page.goto('http://localhost:PORT/YOUR-PATH'); + await expect(page).toHaveScreenshot('ui-state.png'); + }); + ``` + +### Including Screenshots in PRs + +1. **Save screenshots in a dedicated directory**: + ```bash + mkdir -p /tmp/pr-screenshots + mv *.png /tmp/pr-screenshots/ + ``` + +2. **Upload screenshots to an image hosting service** (if needed): + - Use GitHub's issue/PR comment attachment feature + - Use temporary image hosting services for review purposes + +3. **Include screenshots in PR description**: + Add a "Screenshots" section to your PR description: + ```markdown + ## Screenshots + + ### Before + ![Before Changes](url-to-before-screenshot) + + ### After + ![After Changes](url-to-after-screenshot) + + ### Description + Brief description of what changed visually. + ``` + +4. **Add screenshots as PR comments**: + If you can't edit the PR description directly, add screenshots as a comment: + ```markdown + 📸 **UI Changes Screenshot** + + Here are screenshots showing the visual changes made in this PR: + + **Before:** + ![Before](url-to-screenshot) + + **After:** + ![After](url-to-screenshot) + ``` + +### Screenshot Best Practices + +1. **Capture the relevant area**: Focus on the changed UI elements, but include enough context +2. **Use consistent viewport sizes**: Stick to common resolutions (e.g., 1920x1080, 1366x768) +3. **Show multiple states** (if applicable): + - Default state + - Hover state + - Active/clicked state + - Error state + - Loading state +4. **Annotate if helpful**: Add arrows or highlights to draw attention to specific changes +5. **Include mobile views**: For responsive changes, capture both desktop and mobile viewports + +### Example Playwright Script for Common Scenarios + +#### Capturing Multiple Views: +```javascript +const { chromium } = require('playwright'); + +(async () => { + const browser = await chromium.launch(); + const page = await browser.newPage(); + + // Desktop view + await page.setViewportSize({ width: 1920, height: 1080 }); + await page.goto('http://localhost:3000/dashboard'); + await page.screenshot({ path: '/tmp/pr-screenshots/dashboard-desktop.png', fullPage: true }); + + // Mobile view + await page.setViewportSize({ width: 375, height: 667 }); + await page.screenshot({ path: '/tmp/pr-screenshots/dashboard-mobile.png', fullPage: true }); + + // Specific component + const component = await page.locator('.my-changed-component'); + await component.screenshot({ path: '/tmp/pr-screenshots/component-detail.png' }); + + await browser.close(); +})(); +``` + +#### Capturing Interactive States: +```javascript +const { chromium } = require('playwright'); + +(async () => { + const browser = await chromium.launch(); + const page = await browser.newPage(); + await page.goto('http://localhost:3000/form'); + + // Default state + await page.screenshot({ path: '/tmp/pr-screenshots/form-default.png' }); + + // Hover state + await page.hover('button.submit'); + await page.screenshot({ path: '/tmp/pr-screenshots/form-hover.png' }); + + // Filled state + await page.fill('input[name="username"]', 'testuser'); + await page.screenshot({ path: '/tmp/pr-screenshots/form-filled.png' }); + + await browser.close(); +})(); +``` + +## Workflow Summary + +1. Identify the issue or feature to implement +2. Make code changes following best practices +3. **If UI is affected**: + - Set up local environment to run the application + - Use Playwright to capture "before" and "after" screenshots + - Save screenshots to `/tmp/pr-screenshots/` +4. Run tests and ensure everything passes +5. Create PR with detailed description +6. **Include screenshots** in PR description or as a comment +7. Address review feedback + +## Additional Resources + +- [Playwright Documentation](https://playwright.dev/) +- [Playwright Screenshots Guide](https://playwright.dev/docs/screenshots) +- [Contributing Guidelines](../../CONTRIBUTING.md) +- [Pull Request Template](../PULL_REQUEST_TEMPLATE.md) diff --git a/.github/agents/screenshot-guide.md b/.github/agents/screenshot-guide.md new file mode 100644 index 0000000000..0bc622395d --- /dev/null +++ b/.github/agents/screenshot-guide.md @@ -0,0 +1,226 @@ +# Screenshot Capture Quick Guide + +## TL;DR +When making UI changes, capture before/after screenshots using Playwright and include them in your PR. + +## Quick Start + +### 1. Install Playwright +```bash +npm install -D @playwright/test +npx playwright install chromium +``` + +### 2. Basic Screenshot Script +Save as `/tmp/capture-ui.js`: +```javascript +const { chromium } = require('playwright'); + +(async () => { + const browser = await chromium.launch(); + const page = await browser.newPage(); + + // Set viewport size + await page.setViewportSize({ width: 1920, height: 1080 }); + + // Navigate to your changed page + await page.goto('http://localhost:PORT/your-path'); + await page.waitForLoadState('networkidle'); + + // Take screenshot + await page.screenshot({ + path: '/tmp/pr-screenshots/my-change.png', + fullPage: true + }); + + await browser.close(); +})(); +``` + +### 3. Run It +```bash +mkdir -p /tmp/pr-screenshots +node /tmp/capture-ui.js +``` + +## When to Screenshot + +✅ **DO capture screenshots for:** +- New UI components or pages +- Layout changes +- Style/theme modifications +- Visual bug fixes +- Responsive design changes +- Dashboard or console updates + +❌ **DON'T need screenshots for:** +- Backend API changes +- Database schema updates +- Pure logic/algorithm changes +- Non-visual bug fixes +- Configuration changes + +## Screenshot Checklist + +- [ ] Capture "before" state (if possible) +- [ ] Make your code changes +- [ ] Capture "after" state +- [ ] Use descriptive filenames +- [ ] Include screenshots in PR description or comment +- [ ] Capture both desktop and mobile views (if responsive) + +## Common Scenarios + +### Compare Before/After +```javascript +// Before changes +await page.screenshot({ path: '/tmp/pr-screenshots/before.png' }); + +// After changes (rebuild/reload your app) +await page.screenshot({ path: '/tmp/pr-screenshots/after.png' }); +``` + +### Multiple Viewports +```javascript +const viewports = [ + { name: 'desktop', width: 1920, height: 1080 }, + { name: 'tablet', width: 768, height: 1024 }, + { name: 'mobile', width: 375, height: 667 } +]; + +for (const viewport of viewports) { + await page.setViewportSize(viewport); + await page.screenshot({ + path: `/tmp/pr-screenshots/${viewport.name}.png` + }); +} +``` + +### Specific Component +```javascript +// Screenshot just the changed component +const element = await page.locator('.my-component'); +await element.screenshot({ + path: '/tmp/pr-screenshots/component.png' +}); +``` + +### Interactive States +```javascript +// Default +await page.screenshot({ path: '/tmp/pr-screenshots/default.png' }); + +// Hover +await page.hover('button.submit'); +await page.screenshot({ path: '/tmp/pr-screenshots/hover.png' }); + +// Active/Focus +await page.click('input[name="search"]'); +await page.screenshot({ path: '/tmp/pr-screenshots/focus.png' }); + +// Error state +await page.click('button.submit'); +await page.waitForSelector('.error-message'); +await page.screenshot({ path: '/tmp/pr-screenshots/error.png' }); +``` + +## Including in PR + +### Option 1: Upload to PR Description +```markdown +## Screenshots + +### Before +![Before](url-to-before-image) + +### After +![After](url-to-after-image) +``` + +### Option 2: Add as Comment +Drag and drop images into a PR comment or paste from clipboard. + +### Option 3: Use GitHub CLI +```bash +gh pr comment PR_NUMBER --body "📸 Screenshots attached" -F /tmp/pr-screenshots/screenshot.png +``` + +## Pro Tips + +1. **Consistent sizing**: Use standard viewport sizes (1920x1080, 1366x768) +2. **Full page**: Use `fullPage: true` to capture scrollable content +3. **Wait for content**: Use `waitForLoadState('networkidle')` to ensure everything loads +4. **Dark/Light mode**: Capture both themes if your change affects them +5. **Annotations**: Use image editing tools to highlight specific changes + +## Troubleshooting + +### "Browser not installed" +```bash +npx playwright install chromium +``` + +### "Cannot connect to localhost" +Make sure your dev server is running: +```bash +npm run dev # or your start command +``` + +### "Page not loading" +Add explicit waits: +```javascript +await page.waitForSelector('.main-content'); +await page.waitForTimeout(1000); // Last resort +``` + +## Full Example + +```javascript +const { chromium } = require('playwright'); +const fs = require('fs'); + +(async () => { + // Ensure screenshot directory exists + const screenshotDir = '/tmp/pr-screenshots'; + if (!fs.existsSync(screenshotDir)) { + fs.mkdirSync(screenshotDir, { recursive: true }); + } + + const browser = await chromium.launch(); + const page = await browser.newPage(); + + // Test your changes on different pages + const pages = [ + { url: 'http://localhost:3000/dashboard', name: 'dashboard' }, + { url: 'http://localhost:3000/settings', name: 'settings' } + ]; + + for (const pageInfo of pages) { + console.log(`Capturing ${pageInfo.name}...`); + + await page.goto(pageInfo.url); + await page.waitForLoadState('networkidle'); + + // Desktop + await page.setViewportSize({ width: 1920, height: 1080 }); + await page.screenshot({ + path: `${screenshotDir}/${pageInfo.name}-desktop.png`, + fullPage: true + }); + + // Mobile + await page.setViewportSize({ width: 375, height: 667 }); + await page.screenshot({ + path: `${screenshotDir}/${pageInfo.name}-mobile.png`, + fullPage: true + }); + } + + await browser.close(); + console.log('Screenshots saved to', screenshotDir); +})(); +``` + +## More Information + +For complete details, see [code-change-agent.md](./code-change-agent.md). diff --git a/.github/workflows/issue-triage.md b/.github/workflows/issue-triage.md index 2b4739988a..ec3661d237 100644 --- a/.github/workflows/issue-triage.md +++ b/.github/workflows/issue-triage.md @@ -75,4 +75,5 @@ You're a triage assistant for GitHub issues. Your task is to analyze issue #${{ - If you have possible reproduction steps, include them in the comment - If you have any debugging strategies, include them in the comment - If appropriate break the issue down to sub-tasks and write a checklist of things to do. + - **If the issue mentions UI/visual bugs or changes**, remind contributors to include screenshots in their PR using the guidance in `.github/agents/code-change-agent.md` - Use collapsed-by-default sections in the GitHub markdown to keep the comment tidy. Collapse all sections except the short main summary at the top.