|
| 1 | +--- |
| 2 | +description: Writing a GitHub pull request |
| 3 | +alwaysApply: false |
| 4 | +--- |
| 5 | +# GitHub description guidelines |
| 6 | + |
| 7 | +Note for Cursor: If a ticket (GitHub issue or Jira ticket) is not provided by the prompt, prompt the user to supply one before generating the description or pull request content. |
| 8 | + |
| 9 | +When prompted to create a GitHub description, output the following: |
| 10 | + |
| 11 | +- Title |
| 12 | +- Labels |
| 13 | +- Description |
| 14 | + |
| 15 | +Output results in the chat window in a way that can be copied and pasted into GitHub. |
| 16 | + |
| 17 | +## GitHub markdown formatting rules |
| 18 | + |
| 19 | +Use these syntax rules when writing GitHub descriptions: |
| 20 | + |
| 21 | +- `##` through `######` - Headings (use `##` for main, `###` for secondary, etc.) |
| 22 | +- `**text**` - Bold text |
| 23 | +- `` `code` `` - Inline code |
| 24 | +- ```` ```language` ``` - Language-specific code blocks |
| 25 | +- `[text](url)` - Links |
| 26 | +- `-` - Bullet points |
| 27 | +- `1.` - Numbered list items |
| 28 | +- `>` - Blockquotes for important notes |
| 29 | +- `~~text~~` - Strikethrough for deprecated content |
| 30 | + |
| 31 | +## Title format |
| 32 | + |
| 33 | +- Use the format: `[Component] Brief description of change or issue` |
| 34 | +- Keep titles concise but descriptive (under 80 characters) |
| 35 | +- Use present tense for the description (e.g., "Add" not "Added") |
| 36 | +- For PRs, include the component name in brackets if applicable |
| 37 | + |
| 38 | +## Description structure |
| 39 | + |
| 40 | +- Present title, labels, and type before description content |
| 41 | +- Include links to related issues, RFCs, or documentation when applicable |
| 42 | +- All descriptions must include clear acceptance criteria or expected outcomes |
| 43 | +- Provide enough context so anyone can understand the objective |
| 44 | +- Use prefixes in titles: [Bug], [Fix], [Docs], [Refactor], [Research], [S2], [Test] |
| 45 | + |
| 46 | +Examples: |
| 47 | + |
| 48 | +- [bug]: |
| 49 | +- [Bug(component)]: |
| 50 | +- [fix]: |
| 51 | +- [Fix(component)]: |
| 52 | +- [docs]: |
| 53 | +- [Docs(component)]: |
| 54 | + |
| 55 | +## Severity classification |
| 56 | + |
| 57 | +- SEV1: Critical - System down, data loss, security breach |
| 58 | +- SEV2: High - Major feature broken, significant user impact |
| 59 | +- SEV3: Medium - Feature partially broken, moderate impact |
| 60 | +- SEV4: Low - Minor issues, minimal user impact |
| 61 | +- SEV5: Trivial - Cosmetic issues, no functional impact |
| 62 | + |
| 63 | +## Best practices |
| 64 | + |
| 65 | +- Link to relevant issues using the format: `#issue-number` |
| 66 | +- Include component name in brackets if applicable: `[sp-button]` |
| 67 | +- Add relevant labels for easier filtering |
| 68 | +- Attach screenshots or videos for visual changes |
| 69 | +- Reference design specs or documentation when available |
| 70 | +- Use descriptive commit messages when linking to PRs |
| 71 | +- Include reproduction steps for bugs |
| 72 | +- Add environment information when relevant |
| 73 | + |
| 74 | +## Acceptance criteria |
| 75 | + |
| 76 | +- Write criteria in "Given/When/Then" format |
| 77 | +- Make criteria specific and testable |
| 78 | +- Include edge cases and error scenarios |
| 79 | +- Consider accessibility requirements |
| 80 | +- Include performance considerations when relevant |
| 81 | + |
| 82 | +## Labels |
| 83 | + |
| 84 | +Use the following labels to categorize pull requests. Only use labels that exist in the repository: |
| 85 | + |
| 86 | +### Priority and release labels |
| 87 | + |
| 88 | +- `1.0.0`: Issues that should be addressed for a 1.0 release |
| 89 | +- `2.0.0`: Issues for 2.0 release |
| 90 | +- `Breaking`: Breaking changes |
| 91 | + |
| 92 | +### Platform and browser labels |
| 93 | + |
| 94 | +- `Android`: Android-specific issues |
| 95 | +- `Browser: Chrome`: Chrome browser issues |
| 96 | +- `Browser: Edge (Legacy)`: Issue with pre-chromium Edge |
| 97 | +- `Browser: FireFox`: Firefox browser issues |
| 98 | +- `Browser: Safari`: Safari browser issues |
| 99 | + |
| 100 | +### Development and process labels |
| 101 | + |
| 102 | +- `a11y`: Issues related to accessibility |
| 103 | +- `API`: Changes to component APIs or interfaces |
| 104 | + |
| 105 | +### Additional labels (partial list) |
| 106 | + |
| 107 | +Note: The repository has 160 labels total. For a complete list, visit [https://github.com/adobe/spectrum-web-components/labels](https://github.com/adobe/spectrum-web-components/labels) |
| 108 | + |
| 109 | +Common additional labels include: |
| 110 | + |
| 111 | +- `chore`: Routine tasks, maintenance, or non-feature changes |
| 112 | +- `dependencies`: Updates or changes to project dependencies |
| 113 | +- `docs`: Documentation updates or improvements |
| 114 | +- `enhancement`: Improvements to existing features |
| 115 | +- `feature`: New feature implementations |
| 116 | +- `i18n`: Internationalization and localization work |
| 117 | +- `iOS`: iOS-specific issues and bugs |
| 118 | +- `mobile`: Mobile platform issues and responsive design |
| 119 | +- `performance`: Performance-related improvements or regressions |
| 120 | +- `refactor`: Code restructuring and refactoring work |
| 121 | +- `regression`: Previously working functionality that is now broken |
| 122 | +- `release`: Release process or versioning changes |
| 123 | +- `research`: Tasks requiring investigation or research |
| 124 | +- `RFC`: Request for Comments or design discussions |
| 125 | +- `testing`: Test implementation or testing infrastructure work |
| 126 | + |
| 127 | +## Pull request guidelines |
| 128 | + |
| 129 | +- Use conventional commit messages |
| 130 | +- Keep PRs focused and small when possible |
| 131 | +- Include tests for new features |
| 132 | +- Update documentation when APIs change |
| 133 | +- Add screenshots for visual changes |
| 134 | +- Link to related issues using keywords like "Fixes #123" or "Closes #456" |
| 135 | +- Request reviews from appropriate team members |
| 136 | +- Use draft PRs for work in progress |
| 137 | + |
| 138 | +## Templates |
| 139 | + |
| 140 | +### Pull request template |
| 141 | + |
| 142 | +**Note:** All pull requests should include the `ready-for-review` label. |
| 143 | + |
| 144 | +**When returning the template, check off the author requirements in the Author's checklist section. Do not check off the Manual review test cases or Device review sections as these are for reviewers to complete.** |
| 145 | + |
| 146 | +```markdown |
| 147 | +<!--- |
| 148 | + - Following conventional commit format, provide a general summary of your changes in the title above. |
| 149 | + - Acceptable commit types in order of severity (high to low): feat, fix, docs, style, chore, perf, and test. Commit types are defined in PULL_REQUESTS.md. |
| 150 | + - For example,`type(component): general summary` |
| 151 | +--> |
| 152 | + |
| 153 | +## Description |
| 154 | + |
| 155 | +<!--- Describe your changes in detail --> |
| 156 | + |
| 157 | +## Motivation and context |
| 158 | + |
| 159 | +<!--- Why is this change required? What problem does it solve? --> |
| 160 | + |
| 161 | +## Related issue(s) |
| 162 | + |
| 163 | +<!--- |
| 164 | + - If suggesting a new feature or change, please discuss it in an issue first. |
| 165 | + - If fixing a bug, include the issue number where the reviewers can find a description of the bug with steps to reproduce. |
| 166 | + - If you're an Adobe employee, add a Jira ticket number but DO NOT LINK directly to Jira. |
| 167 | +--> |
| 168 | + |
| 169 | +- fixes [Issue Number] |
| 170 | + |
| 171 | +## Screenshots (if appropriate) |
| 172 | + |
| 173 | + |
| 174 | +## Author's checklist |
| 175 | + |
| 176 | +<!--- Go over all the following points, and put an `x` in all the boxes that apply. If you're unsure about any of these, don't hesitate to ask. We're here to help! --> |
| 177 | + |
| 178 | +- [ ] I have read the **[CONTRIBUTING](<(https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTING.md)>)** and **[PULL_REQUESTS](<(https://github.com/adobe/spectrum-web-components/blob/main/PULL_REQUESTS.md)>)** documents. |
| 179 | +- [ ] I have reviewed at the Accessibility Practices for this feature, see: [Aria Practices](https://www.w3.org/TR/wai-aria-practices/) |
| 180 | +- [ ] I have added automated tests to cover my changes. |
| 181 | +- [ ] I have included a well-written changeset if my change needs to be published. |
| 182 | +- [ ] I have included updated documentation if my change required it. |
| 183 | + |
| 184 | + |
| 185 | +## Reviewer's checklist |
| 186 | + |
| 187 | +- [ ] Includes a Github Issue with appropriate flag or Jira ticket number without a link |
| 188 | +- [ ] Includes thoughtfully written changeset if changes suggested include `patch`, `minor`, or `major` features |
| 189 | +- [ ] Automated tests cover all use cases and follow best practices for writing |
| 190 | +- [ ] Validated on all supported browsers |
| 191 | +- [ ] All VRTs are approved before the author can update Golden Hash |
| 192 | + |
| 193 | +### Manual review test cases |
| 194 | + |
| 195 | +<!--- |
| 196 | + - For the author, please describe in detail what reviewers should test. |
| 197 | + - Include links and manual steps for how the reviewer should go through to verify your changes. |
| 198 | + - Be sure to include all areas of the codebase that might be affected. Any components that use these changes for a dependency should be cross-checked for regressions. |
| 199 | + - For example, changes to Menu Item will affect Picker, Menu, and Action Menu. |
| 200 | +--> |
| 201 | + |
| 202 | +- [ ] _Descriptive Test Statement_ |
| 203 | + |
| 204 | + 1. Go [here](url) |
| 205 | + 2. Do this action |
| 206 | + 3. Expect this result |
| 207 | + |
| 208 | +- [ ] _Descriptive Test Statement_ |
| 209 | + 1. Go [here](url) |
| 210 | + 2. Do this action |
| 211 | + 3. Expect this result |
| 212 | + |
| 213 | +### Device review |
| 214 | + |
| 215 | +<!--- Verify the above manual tests and visual accuracy utilizing an emulator like Polypane browser or on an actual device. --> |
| 216 | + |
| 217 | +- [ ] Did it pass in Desktop? |
| 218 | +- [ ] Did it pass in (emulated) Mobile? |
| 219 | +- [ ] Did it pass in (emulated) iPad? |
| 220 | + |
| 221 | +``` |
1 | 222 | # GitHub description guidelines |
2 | 223 |
|
3 | 224 | Note for Cursor: If a ticket (GitHub issue or Jira ticket) is not provided by the prompt, prompt the user to supply one before generating the description or pull request content. |
|
0 commit comments