|
| 1 | +<!-- Generated breadcrumbs - DO NOT EDIT --> |
| 2 | + |
| 3 | +[CONTRIBUTOR-DOCS](../README.md) / [Contributor guides](README.md) / Making a pull request |
| 4 | + |
| 5 | +<!-- Document title (editable) --> |
| 6 | + |
| 7 | +# Making a pull request |
| 8 | + |
| 9 | +<!-- Generated TOC - DO NOT EDIT --> |
| 10 | + |
| 11 | +<details open> |
| 12 | +<summary><strong>In this doc</strong></summary> |
| 13 | + |
| 14 | +- [Scoping and planning your PR](#scoping-and-planning-your-pr) |
| 15 | + - [Testing](#testing) |
| 16 | + - [Documentation](#documentation) |
| 17 | + - [Code formatting](#code-formatting) |
| 18 | + - [Accessibility](#accessibility) |
| 19 | +- [Developing your PR](#developing-your-pr) |
| 20 | + - [Branch naming](#branch-naming) |
| 21 | + - [Changeset requirements](#changeset-requirements) |
| 22 | + - [Conventional commits](#conventional-commits) |
| 23 | +- [Submitting your PR](#submitting-your-pr) |
| 24 | + - [Pull request template](#pull-request-template) |
| 25 | + - [Labels for PR authors](#labels-for-pr-authors) |
| 26 | +- [Specific requirements by element type](#specific-requirements-by-element-type) |
| 27 | + - [New components](#new-components) |
| 28 | + |
| 29 | +</details> |
| 30 | + |
| 31 | +<!-- Document content (editable) --> |
| 32 | + |
| 33 | +This document outlines our team's expectations and best practices for creating and submitting pull requests for Spectrum Web Components. |
| 34 | + |
| 35 | +## Scoping and planning your PR |
| 36 | + |
| 37 | +### Testing |
| 38 | + |
| 39 | +Quality and stability are important. We require writing tests for any fixes or features you introduce. This helps ensure: |
| 40 | + |
| 41 | +- Bugs don't resurface later. |
| 42 | +- New features work as intended for all users. |
| 43 | +- Overall library reliability remains high. |
| 44 | + |
| 45 | +Read about our testing guidance in the [README.md](../../README.md). |
| 46 | + |
| 47 | +If you're unsure how to write tests for certain parts of the library, don't hesitate to ask maintainers for guidance. We appreciate every effort to keep the code solid! |
| 48 | + |
| 49 | +### Documentation |
| 50 | + |
| 51 | +In addition to well-tested code, documentation is crucial. Whenever you add or change a feature, include documentation for it in the relevant areas: |
| 52 | + |
| 53 | +- **README.md**: Each component has a README within its directory. Ensure your changes are included here. This file is used in our generated documentation site. |
| 54 | +- **Comment annotations**: We use comment-based documentation ([JSDocs](https://jsdoc.app/)) so that references are generated automatically where possible. |
| 55 | + |
| 56 | +Accessible, helpful docs are a huge win for everyone, especially newcomers. |
| 57 | + |
| 58 | +### Code formatting |
| 59 | + |
| 60 | +We rely on automated tools like Prettier, ESLint, and Stylelint to enforce style preferences. Setting up these tools in your editor saves time and prevents minor style conflicts from slowing down reviews. |
| 61 | + |
| 62 | +### Accessibility |
| 63 | + |
| 64 | +Since this project is used by a diverse audience, the accessibility of our product is of utmost importance. Features will be evaluated for inclusivity by: |
| 65 | + |
| 66 | +- The use of semantic markup. |
| 67 | +- Labeled interactive elements with appropriate accordance's. |
| 68 | +- Accounting for appropriate states, such as focus and keyboard navigation, according to [standards](https://www.w3.org/WAI/perspective-videos/keyboard/). |
| 69 | + |
| 70 | +If you're unsure about an accessibility detail, the [Web Accessibility Initiative (WAI) ARIA Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/patterns/) is a good place to start. You can also open a discussion or ask in your PR. |
| 71 | + |
| 72 | +--- |
| 73 | + |
| 74 | +## Developing your PR |
| 75 | + |
| 76 | +### Branch naming |
| 77 | + |
| 78 | +We use a straightforward branch naming convention: |
| 79 | + |
| 80 | +- `[username]/[short-description]` (e.g., `alex/fix-dropdown-bug`) |
| 81 | +- If referencing a known issue, incorporate the issue number (e.g., `alex/123-fix-dropdown-bug`) |
| 82 | + |
| 83 | +### Changeset requirements |
| 84 | + |
| 85 | +For PRs that add or update a component: |
| 86 | + |
| 87 | +- Must include a changeset to trigger the release train and update the CHANGELOG |
| 88 | +- Changeset type should be one of: |
| 89 | + - `patch` - for bug fixes only |
| 90 | + - `minor` - for new components or new APIs in an existing component |
| 91 | + - `major` - for breaking changes to a component or public library API |
| 92 | + |
| 93 | +### Conventional commits |
| 94 | + |
| 95 | +We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification to make change tracking predictable: |
| 96 | + |
| 97 | +Format: `type(component?): subject` |
| 98 | + |
| 99 | +The component is optional but should reference the package you are updating. |
| 100 | + |
| 101 | +Types include: |
| 102 | + |
| 103 | +- `feat`: New features or enhancements |
| 104 | +- `fix`: Bug fixes |
| 105 | +- `docs`: Documentation changes |
| 106 | +- `style`: Formatting, linting (not CSS changes) |
| 107 | +- `chore`: Build tooling, repo management, dependency updates |
| 108 | +- `perf`: Performance improvements |
| 109 | +- `test`: Adding or updating tests |
| 110 | + |
| 111 | +Examples: |
| 112 | + |
| 113 | +- `feat(sp-card): add shadow styles for theme consistency` |
| 114 | +- `fix(sp-action-menu): correct arrow key navigation in nested menus` |
| 115 | +- `docs: clarify how to submit bug reports` |
| 116 | + |
| 117 | +For breaking changes, add a `!` after the type/scope: |
| 118 | + |
| 119 | +- `feat(sp-button)!: change API for icon placement` |
| 120 | + |
| 121 | +--- |
| 122 | + |
| 123 | +## Submitting your PR |
| 124 | + |
| 125 | +### Pull request template |
| 126 | + |
| 127 | +When creating a pull request, you'll be presented with our template. Complete all sections to the best of your ability, including: |
| 128 | + |
| 129 | +- Description of the changes |
| 130 | +- Related issues (using proper [GitHub keywords](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests#linking-a-pull-request-to-an-issue) to auto-close issues i.e. `fixes`, `resolves`, or `closes`) |
| 131 | +- Type of change in the PR title (bug fix, feature, breaking change) |
| 132 | +- Steps you took to test your changes that reviewers can follow to also test them |
| 133 | +- Checklist of items completed |
| 134 | +- Screenshots/videos for visual changes |
| 135 | + |
| 136 | +Incomplete templates may delay the review process. |
| 137 | + |
| 138 | +### Labels for PR authors |
| 139 | + |
| 140 | +As a PR author, you can use these labels to communicate the status of your pull request: |
| 141 | + |
| 142 | +- `ready-for-review`: PR is ready for maintainer review |
| 143 | +- `WIP`: PR is still being worked on, not ready for review |
| 144 | +- `needs-self-review`: You plan to do a self-review before requesting maintainer review |
| 145 | +- `help-wanted`: You need extra attention or assistance on this PR |
| 146 | +- `breaking-change`: PR contains changes that break backward compatibility |
| 147 | +- `Component: [Name]`: PR affects this component |
| 148 | + |
| 149 | +For a complete list of labels and their meanings, including reviewer-specific labels, see [Participating in PR reviews](04_participating-in-pr-reviews.md#labels-and-their-meanings). |
| 150 | + |
| 151 | +--- |
| 152 | + |
| 153 | +## Specific requirements by element type |
| 154 | + |
| 155 | +### New components |
| 156 | + |
| 157 | +When creating or reviewing new components, ensure: |
| 158 | + |
| 159 | +#### Documentation |
| 160 | + |
| 161 | +- README contains a clear description and minimal example |
| 162 | +- Inline documentation for all public APIs |
| 163 | +- Accessibility documentation that aligns with WCAG patterns |
| 164 | + |
| 165 | +See [Documenting a component](https://opensource.adobe.com/spectrum-web-components/guides/adding-component/#documenting-the-component) for more information on our documentation standards and structure. |
| 166 | + |
| 167 | +#### API documentation utilizing JSDocs |
| 168 | + |
| 169 | +- **Slots**: All slots documented in the element class docblock |
| 170 | +- **Events**: All dispatched events documented with `@fires` docblock |
| 171 | +- **Class fields**: All public/protected fields have proper docblocks |
| 172 | +- **Methods**: All public/protected methods have docblocks with parameters and return types |
| 173 | +- **CSS custom properties**: All public CSS custom properties documented |
| 174 | +- **CSS shadow parts**: All shadow parts documented |
| 175 | + |
| 176 | +#### Technical requirements |
| 177 | + |
| 178 | +- Component follows established patterns and conventions |
| 179 | +- Accessibility is thoroughly considered |
| 180 | +- Responsive design best practices are followed |
| 181 | +- Supported cross-browser compatibility is verified |
0 commit comments