|
| 1 | +## Step 3: Customize Your Review |
| 2 | + |
| 3 | +The school's coding standards are crucial for maintaining the activities website. You've noticed that teachers are using different visual styles and coding patterns. With such diverse programming backgrounds and priorities among your teacher-collaborators, let's customize Copilot's review behavior to align with the school's educational programming standards. |
| 4 | + |
| 5 | +### 📖 Theory: Repository Custom Instructions |
| 6 | + |
| 7 | +Repository custom instructions allow you to provide Copilot with context about your project standards and preferences. By creating instruction files, you can ensure Copilot's suggestions consistently follow your team's conventions and focus on your specific requirements. You can even have copilot analyze your project and [generate instructions](https://code.visualstudio.com/docs/copilot/customization/custom-instructions#_generate-an-instructions-file-for-your-workspace) for you! |
| 8 | + |
| 9 | +**Types of Instructions:** |
| 10 | + |
| 11 | +- **Repository-wide instructions**: Applies to all code in the repository. Ex: `.github/copilot-instructions.md` |
| 12 | +- **Path-specific instructions**: Applies to specific files to create focused criteria for different parts of your codebase. Ex: `.github/instructions/NAME.instructions.md`. |
| 13 | + |
| 14 | +Instructions are written in natural language with Markdown format and typically include: |
| 15 | + |
| 16 | +- Security requirements and checklists |
| 17 | +- Code standards and conventions |
| 18 | +- Performance optimization priorities |
| 19 | +- Team-specific preferences and style guides |
| 20 | +- Language-specific review criteria |
| 21 | + |
| 22 | +Path-specific instruction files include [YAML front matter](https://docs.github.com/en/contributing/writing-for-github-docs/using-yaml-frontmatter) with file [glob patterns](https://code.visualstudio.com/docs/editor/glob-patterns) to target specific files and directories. Examples: |
| 23 | + |
| 24 | +```yaml |
| 25 | +--- |
| 26 | +applyTo: "tests/**/**,docs/*.md" |
| 27 | +--- |
| 28 | +# Testing Guidelines ... |
| 29 | +``` |
| 30 | + |
| 31 | +```yaml |
| 32 | +--- |
| 33 | +applyTo: "docs/*.md,README.md" |
| 34 | +--- |
| 35 | +# Documentation Guidelines ... |
| 36 | +``` |
| 37 | + |
| 38 | +> [!TIP] |
| 39 | +> Repository [custom instructions](https://docs.github.com/en/copilot/how-tos/custom-instructions/adding-repository-custom-instructions-for-github-copilot) work for both local VS Code code reviews and pull request code reviews, ensuring consistency across your development workflow. |
| 40 | +
|
| 41 | +### ⌨️ Activity: Add general instructions |
| 42 | + |
| 43 | +Let's customize Copilot's review considerations by adding custom instructions. |
| 44 | + |
| 45 | +1. In VS Code, ensure you are still on the `add-announcement-banner` branch. |
| 46 | + |
| 47 | +1. Create a file for general repository guidelines. |
| 48 | + |
| 49 | + File location and name: |
| 50 | + |
| 51 | + ```txt |
| 52 | + .github/copilot-instructions.md |
| 53 | + ``` |
| 54 | + |
| 55 | + Content: |
| 56 | + |
| 57 | + ```markdown |
| 58 | + ## Security |
| 59 | + |
| 60 | + - Validate input sanitization practices. |
| 61 | + - Search for risks that might expose user data. |
| 62 | + - Prefer loading configuration and content from the database instead of hard coded content. If absolutely necessary, load it from environment variables or a non-committed config file. |
| 63 | + |
| 64 | + ## Code Quality |
| 65 | + |
| 66 | + - Use consistent naming conventions. |
| 67 | + - Try to reduce code duplication. |
| 68 | + - Prefer maintainability and readability over optimization. |
| 69 | + - If a method is used a lot, try to optimize it for performance. |
| 70 | + - Prefer explicit error handling over silent failures. |
| 71 | + ``` |
| 72 | + |
| 73 | +### ⌨️ Activity: Add focused instructions |
| 74 | + |
| 75 | +Let's create specific Copilot's review considerations for the frontend and backend. |
| 76 | + |
| 77 | +1. Create a file for the frontend-specific guidelines. |
| 78 | + |
| 79 | + > ❗️ **Important**: Make sure to put file-specific instructions in the `.github/instructions/` folder, not the `.github/` folder. |
| 80 | +
|
| 81 | + File location and name: |
| 82 | + |
| 83 | + ```txt |
| 84 | + .github/instructions/frontend.instructions.md |
| 85 | + ``` |
| 86 | + |
| 87 | + Content: |
| 88 | + |
| 89 | + ```markdown |
| 90 | + --- |
| 91 | + applyTo: "*.html,*.css,*.js" |
| 92 | + --- |
| 93 | + |
| 94 | + ## Frontend Guidelines |
| 95 | + |
| 96 | + - Use accessibility attributes (alt text, aria labels) and color schemes. |
| 97 | + - Use responsive design for compatibility with mobile devices. |
| 98 | + - Validate HTML structure and semantic elements |
| 99 | + ``` |
| 100 | + |
| 101 | +1. Create a file for the backend-specific guidelines. |
| 102 | + |
| 103 | + File location and name: |
| 104 | + |
| 105 | + ```txt |
| 106 | + .github/instructions/backend.instructions.md |
| 107 | + ``` |
| 108 | + |
| 109 | + Content: |
| 110 | + |
| 111 | + ```markdown |
| 112 | + --- |
| 113 | + applyTo: "backend/**/*,*.py" |
| 114 | + --- |
| 115 | + |
| 116 | + ## Backend Guidelines |
| 117 | + |
| 118 | + - All API endpoints must be defined in the `routers` folder. |
| 119 | + - Load example database content from the `database.py` file. |
| 120 | + - Error handling is only logged on the server. Do not propagate to the frontend. |
| 121 | + - Ensure all APIs are explained in the documentation. |
| 122 | + - Verify changes in the backend are reflected in the frontend (`src/static/**`). If possible breaking changes are found, mention them to the developer. |
| 123 | + ``` |
| 124 | + |
| 125 | +1. Commit and push the instruction files. |
| 126 | + |
| 127 | +> [!TIP] |
| 128 | +> VS Code has a built-in commands to help manage instructions. Try opening the command pallette and searching for `instructions`. |
| 129 | +
|
| 130 | +### ⌨️ Activity: Request another review |
| 131 | + |
| 132 | +With our new instructions defined, Copilot now has a better idea of what is important for our project. Let's ask for another review. |
| 133 | + |
| 134 | +1. In VS Code, Ensure the instructions are indeed committed and push to the repository. |
| 135 | + |
| 136 | +1. In the web browser, return to the recently created pull request. |
| 137 | + |
| 138 | +1. In the top right, find the **Reviewers** menu and **Re-request review** button next to **Copilot**. Click it and wait a moment for Copilot to add comments on the pull request. |
| 139 | + |
| 140 | + <img width="300" alt="screenshot of re-review button" src="https://github.com/user-attachments/assets/c45aa8de-278d-46e7-bfe2-2dc6b574e11e"/> |
| 141 | + |
| 142 | + > 🪧 **Note:** If you are too quick after pushing new commits, you may have to wait a moment for the button to appear, or refresh the page. |
| 143 | +
|
| 144 | +1. Observe that Copilot's feedback now differs from the previous review. |
| 145 | + |
| 146 | +1. With the review requested, wait a moment for Mona to check your work, provide feedback, and share the next lesson. |
| 147 | + |
| 148 | +<details> |
| 149 | +<summary>Having trouble? 🤷</summary><br/> |
| 150 | + |
| 151 | +- If you forgot to add a custom instruction (or made a typo), try fixing the mistake and asking Copilot for another review. This will inform Mona to check your work again. |
| 152 | + |
| 153 | +</details> |
0 commit comments