You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+53-51
Original file line number
Diff line number
Diff line change
@@ -1,51 +1,53 @@
1
+
# Contributing Best Practices
2
+
1
3
Welcome! We’re excited you’re interested in improving Spectrum Web Components. Whether you’re reporting bugs, adding new features, writing documentation, or helping other users, your contributions make this project better for everyone.
2
4
3
5
Here you’ll find a broad overview of how you can get involved. Please read through these guidelines to help keep the contribution process smooth and to ensure we’re all on the same page.
If you need support or have a question about how something works, filing an issue is the best place to start. A team member will be in touch to either triage your issue or follow-up with you in the comments.
41
43
42
-
##1.2. Internal Contributors
44
+
###Internal Contributors
43
45
44
46
If you work for Adobe, our Slack channel #spectrum_web_components has some great workflows to get you started. Be sure to read the Welcome Canvas when you join.
45
47
46
48
---
47
49
48
-
#2. How can you Contribute
50
+
##How can you Contribute
49
51
50
52
There’s a common misconception that you need to code in order to contribute. In reality, there are many different ways to help:
51
53
@@ -60,20 +62,20 @@ Of course, contributing code is also welcome from fixing a bug to building a bra
60
62
61
63
---
62
64
63
-
#3. Contributor License Agreement
65
+
##Contributor License Agreement
64
66
65
67
We require all external contributors to sign our Contributor License Agreement (CLA). If you haven’t signed it before making your first contribution, please do so—otherwise, we can’t merge your changes.
66
68
67
69
---
68
70
69
-
#4. Code of Conduct
71
+
##Code of Conduct
70
72
71
73
Spectrum Web Components abides by the Adobe Code of Conduct. By participating, you agree to treat all community members kindly and respectfully. We’re committed to fostering a welcoming, inclusive environment.
72
74
Should any behavior fall short of these expectations, please report it to <Grp-opensourceoffice@adobe.com>.
73
75
74
76
---
75
77
76
-
#5. Using the Issue Tracker
78
+
##Using the Issue Tracker
77
79
78
80
We use GitHub Issues for two purposes:
79
81
@@ -82,7 +84,7 @@ We use GitHub Issues for two purposes:
82
84
83
85
If you’re having a usage issue or need support, do not open an issue. Instead, reference the Community & Support section. This helps us keep issues focused on actual bugs and actionable tasks.
84
86
85
-
##5.1. Before Submitting A Bug Report
87
+
###Before Submitting A Bug Report
86
88
87
89
1. Check the [Open Issues](https://github.com/adobe/spectrum-web-components/issues) to see if the problem has already been reported.
88
90
- TIP: Apply the component label to make your search process more straightforward.
@@ -92,20 +94,20 @@ If you’re having a usage issue or need support, do not open an issue. Instead,
92
94
93
95
---
94
96
95
-
#6. Bug Reports
97
+
##Bug Reports
96
98
97
99
When you file a bug, please use the `Bug Report` template provided in GitHub. Include the following information:
98
100
99
-
1. A concise summary of the problem.
100
-
2. Relevant components involved in the issue.
101
-
3. Issue Severity based on our classifications defined below.
102
-
4. What you expected vs. what actually happened, along with any errors logged in the console.
103
-
5. Steps to reproduce the issue, preferably in an isolated environment, so that we can narrow down where the bug is originating from. (e.g., webcomponents.dev or CodePen). Be detailed if you write out the steps!
- Issue Severity based on our classifications defined below.
104
+
- What you expected vs. what actually happened, along with any errors logged in the console.
105
+
- Steps to reproduce the issue, preferably in an isolated environment, so that we can narrow down where the bug is originating from. (e.g., webcomponents.dev or CodePen). Be detailed if you write out the steps!
Clear bug reports speed up the triage process, help us replicate the issue, and keep the project robust.
107
109
108
-
## Issue severity classification
110
+
###Issue severity classification
109
111
110
112
Providing the correct issue severity classification helps us adequately assess and prioritize your issue. We reserve the right to adjust the severity of your bug during triage.
111
113
Below is our issue severity classification criteria:
Is there something you wish the project did differently? Have a new component in mind? We love hearing new ideas and are eager to collaborate!
126
128
@@ -129,13 +131,13 @@ Is there something you wish the project did differently? Have a new component in
129
131
130
132
---
131
133
132
-
#8. Pull Requests
134
+
##Pull Requests
133
135
134
136
If you plan to fix a bug, create a feature, or improve documentation, follow the [Pull Request Guide](PULL_REQUESTS.md) to ensure you're contribution meets expectations for getting reviewed.
135
137
136
138
---
137
139
138
-
#9. Branches
140
+
##Branches
139
141
140
142
We keep things straightforward with branching:
141
143
@@ -146,15 +148,15 @@ Avoid editing distribution files (if present). Make changes to the source files,
146
148
147
149
---
148
150
149
-
#10. Developing Locally
151
+
##Developing Locally
150
152
151
153
Read the steps outlined in the [README.md](README.md) to get your environment set up.
152
154
153
155
If you encounter hurdles, feel free to ask for help in your pull request or in the community forum.
154
156
155
157
---
156
158
157
-
#11. Testing
159
+
##Testing
158
160
159
161
Quality and stability are important. We require writing tests for any fixes or features you introduce. This helps ensure:
160
162
@@ -168,7 +170,7 @@ If you’re unsure how to write tests for certain parts of the library, don’t
168
170
169
171
---
170
172
171
-
#12. Documentation
173
+
##Documentation
172
174
173
175
In addition to well-tested code, documentation is crucial. Whenever you add or change a feature,include documentation for it in the relevant areas:
174
176
@@ -179,23 +181,23 @@ Accessible, helpful docs are a huge win for everyone, especially newcomers.
179
181
180
182
---
181
183
182
-
#13. Best Practices & Guidelines
184
+
##Best Practices & Guidelines
183
185
184
-
##13.1. Code Formatting
186
+
###Code Formatting
185
187
186
-
We rely on automated tools like Prettier or ESLint to enforce style preferences. Setting up these tools in your editor saves time and prevents minor style conflicts from slowing down reviews.
188
+
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.
187
189
188
-
##13.2. Accessibility
190
+
###Accessibility
189
191
190
192
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:
191
193
192
194
- The use of semantic markup.
193
-
- Labeled interactive elements with appropriate affordances.
195
+
- Labeled interactive elements with appropriate accordance's.
194
196
- Accounting for appropriate states, such as focus and keyboard navigation, according to [standards](https://www.w3.org/WAI/perspective-videos/keyboard/).
195
197
196
198
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.
197
199
198
-
##13.3. Commit Guidelines
200
+
###Commit Guidelines
199
201
200
202
As mentioned previously, we use [Conventional Commit](https://www.conventionalcommits.org) syntax:
201
203
@@ -212,7 +214,7 @@ This helps us track changes in a predictable way and automate versioning.
212
214
213
215
---
214
216
215
-
#14. Thank You
217
+
##Thank You
216
218
217
219
We appreciate everyone who invests time, energy, and expertise into Spectrum Web Components. Your contributions—big or small—help this library evolve to serve a broader audience and remain at a high standard of quality.
@@ -130,16 +130,16 @@ Both reviewers and PR authors should follow these guidelines:
130
130
131
131
#### For Reviewers
132
132
133
-
-**Be specific and constructive**: By providing clear, actionable feedback and explaining why a change is needed, we help contributors make updates to their code more quickly and accurately.
134
-
-**Prioritize Issues**: Focus on important issues first (architecture, functionality, performance) before minor stylistic concerns.
135
-
-**Ask Questions**: When something isn't clear, start with asking questions. We don't assume intent or meaning and focus instead on curiosity and clarification.
136
-
-**Suggest Alternatives**: When pointing out issues, suggest possible solutions or approaches. Leverage the code suggestions feature to streamline applying feedback for the author.
137
-
-**Celebrate good work**: By acknowledging well-written code and good design decisions, we celebrate our contributors and the hard work they put in. Positive reinforcement is valued and makes for a fun and engaging project!
138
-
-**Remember Context**: Consider the PR author's experience level and the scope of changes when providing feedback.
139
-
-**Be Timely**: Complete reviews promptly to avoid blocking progress.
140
-
-**Avoid Nitpicking**: Focus on meaningful improvements rather than personal style preferences that don't violate project standards. Prepend comments with `nit:` to denote that it is non-blocking feedback.
141
-
-**Use Changes Requested Sparingly**: Changes Requested review status should only be used in instances where a bug or regression is still present in the PR.
142
-
-**Review VRTs Thoroughly**: Ensure the diffs in VRT are expected and inform the author via comment if they are approved so they know to update the golden hash.
133
+
-**Maintain Momentum**: Complete reviews in a timely manner to keep the project moving forward.
134
+
-**Provide Clear, Actionable Feedback**: Help contributors succeed by offering specific guidance and explaining the reasoning behind suggested changes.
135
+
-**Offer Solutions**: When identifying areas for improvement, suggest alternative approaches and use code suggestions to make implementation easier.
136
+
-**Seek Understanding**: Ask questions to clarify intent and approach, fostering a collaborative environment for learning and improvement.
137
+
-**Recognize Excellence**: Celebrate well-written code and thoughtful design decisions to encourage continued high-quality contributions.
138
+
-**Focus on Impact**: Prioritize feedback on architecture, functionality, and performance to ensure the most important aspects are addressed first.
139
+
-**Focus on Value**: Prioritize feedback that improves code quality and maintainability over personal style preferences. If you make a suggestion that is non-blocking feedback, prepend the comment with `nit:`.
140
+
-**Consider Context**: Tailor feedback to the PR author's experience level and the scope of changes.
141
+
-**Use Changes Requested Thoughtfully**: Reserve the Changes Requested status for instances where critical issues need to be addressed.
142
+
-**Review VRTs with Care**: Thoroughly examine visual regression test results and communicate approval status to authors.
143
143
144
144
#### For PR Authors
145
145
@@ -191,7 +191,7 @@ When creating or reviewing new components, ensure:
191
191
192
192
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.
193
193
194
-
#### API Documentation
194
+
#### API Documentation Utilizing [JSDocs](https://jsdoc.app/)
195
195
196
196
-**Slots**: All slots documented in the element class docblock
197
197
-**Events**: All dispatched events documented with `@fires` docblock
@@ -205,4 +205,4 @@ See [Documenting a component](https://opensource.adobe.com/spectrum-web-componen
205
205
- Component follows established patterns and conventions
206
206
- Accessibility is thoroughly considered
207
207
- Responsive design best practices are followed
208
-
-Cross-browser compatibility is verified
208
+
-Supported cross-browser compatibility is verified
0 commit comments