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
+47-8
Original file line number
Diff line number
Diff line change
@@ -3,26 +3,33 @@
3
3
Thanks for choosing to contribute! We look forward to improving web applications together. Here you will find information on how to propose bug fixes, suggest improvements, and develop locally.
4
4
5
5
## Better together
6
+
6
7
We believe that the best way to build a better web is together as a community. The React Spectrum project aims to make it easier to build design systems and component libraries with high quality interactions and accessibility for all. The core team and all external contributors follow the same process in order maintain a high quality codebase.
7
8
8
9
## Code of conduct
10
+
9
11
We adhere to the Adobe [code of conduct](https://github.com/adobe/react-spectrum/blob/main/CODE_OF_CONDUCT.md) and by participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].
10
12
11
13
## Reporting issues
14
+
12
15
### Bugs
16
+
13
17
We use [GitHub issues](https://github.com/adobe/react-spectrum/issues) to track work and log bugs. Please check existing issues before filing anything new. We do our best to respond to issues within a few days. If you would like to contribute a fix, please let us know by leaving a comment on the issue.
14
18
15
19
The best way to reduce back and forth on a bug is provide a small code example exhibiting the issue along with steps to reproduce it. If you would like to work on a bugfix yourself, make sure an issue exists first.
16
20
17
21
Please follow the issue templates when filing new ones and add as much information as possible.
18
22
19
23
### Feature requests
24
+
20
25
Our components can always be improved upon. If you have a feature request, you can use our Feature Request issue template. For larger scopes of work, it is a good idea to open a Request For Comments (RFC) first to gather feedback from the team. Please follow our RFC [template](https://github.com/adobe/react-spectrum/blob/main/rfcs/template.md). Make a PR to add your RFC to the [rfcs folder](https://github.com/adobe/react-spectrum/tree/main/rfcs) to give the team and the community a chance to discuss the proposal.
21
26
22
27
### Security issues
28
+
23
29
Security issues shouldn't be reported on this issue tracker. Instead, please follow the directions [here](https://helpx.adobe.com/security/alertus.html) to contact our security team.
24
30
25
31
## Pull Requests
32
+
26
33
For significant changes, it is recommended that you first propose your solution in [an RFC](#feature-requests) and gather feedback.
27
34
28
35
A few things to keep in mind before submitting a pull request:
@@ -36,6 +43,7 @@ A few things to keep in mind before submitting a pull request:
36
43
- Remember that all submissions require review, please be patient.
37
44
38
45
The team will review all pull requests and do one of the following:
Lastly, please follow the pull request template when submitting a pull request!
46
54
47
55
### Contributor License Agreement
56
+
48
57
All third-party contributions to this project must be accompanied by a signed contributor license agreement. This gives Adobe permission to redistribute your contributions as part of the project. [Sign our CLA](https://opensource.adobe.com/cla.html). You only need to submit an Adobe CLA one time, so if you have submitted one previously, you are good to go!
49
58
50
59
## Where to start
60
+
51
61
There are many places to dive into react-spectrum to help out. Before you take on a feature or issue, make sure you become familiar with [our architecture](https://react-spectrum.adobe.com/architecture.html).
52
62
53
63
If you are looking for place to start, consider the following options:
64
+
54
65
- Look for issues tagged with help wanted and/or good first issue.
55
66
- Help triage existing issues by investigating problems and following up on missing information.
56
67
- Update missing or fix existing documentation
57
68
- Review and test open pull requests
58
69
59
70
## Developing
71
+
60
72
When you are ready to start developing you can clone the repo and start storybook.
61
73
Make sure you have the following requirements installed: [node](https://nodejs.org/) (v14.15.0+) and [yarn](https://yarnpkg.com/en/) (v1.22.0+)
62
74
63
75
Fork the repo first using [this guide](https://help.github.com/articles/fork-a-repo), then clone it locally.
You can then run the storybook and browse to [http://localhost:9003](http://localhost:9003) with:
84
+
71
85
```bash
72
86
yarn start
73
87
```
74
88
75
89
Or run the documentation and browse to [http://localhost:1234/](http://localhost:1234/) with:
90
+
76
91
```bash
77
92
yarn start:docs
78
93
```
79
94
80
95
### Component/Hook scaffolding
96
+
81
97
If you are looking to contribute a brand new component or Hook in a package that does not exist yet, please run the following command.
98
+
82
99
```bash
83
100
yarn plop
84
101
```
102
+
85
103
This will start a series of cli prompts to determine what template files and folders should be generated to help quick start your contribution.
86
104
The prompts are as follows:
87
105
88
106
1. What type of project are you setting up?
89
-
- Select "React Spectrum v3"
107
+
108
+
- Select "React Spectrum v3"
90
109
91
110
2. Scope name(s)
92
-
- Select the package scopes that make sense for your contribution (e.g. react-spectrum if you are contributing a component, react-aria for an aria Hook, etc)
111
+
112
+
- Select the package scopes that make sense for your contribution (e.g. react-spectrum if you are contributing a component, react-aria for an aria Hook, etc)
93
113
94
114
3. Package name, all lowercase (e.g. textfield)
95
115
96
116
4. Component name, please use appropriate uppercase (e.g. TextField)
97
-
- If you are contributing a non-component Hook, just enter the name of your Hook.
117
+
118
+
- If you are contributing a non-component Hook, just enter the name of your Hook.
98
119
99
120
5. Component css module name, blank if N/A. If unsure, check @adobe/spectrum-css-temp/components for a module containing the desired css (e.g. textfield)
100
-
- If you cannot find the component CSS module name in @adobe/spectrum-css-temp/components, feel free to reach out to a team member via GitHub Issues or Discussions.
121
+
- If you cannot find the component CSS module name in @adobe/spectrum-css-temp/components, feel free to reach out to a team member via GitHub Issues or Discussions.
101
122
102
123
Upon answering all the prompts, the appropriate package(s) should be generated and ready for modification.
103
124
104
125
**Note:** With regards to the generated docs files, please feel free to remove them if you won't be contributing docs. If you are contributing docs for a new component or Hook, please submit them in a separate pull request so that we can decide when to deploy them to our docs site.
105
126
106
127
### Tests
128
+
107
129
We use [jest](https://jestjs.io/) for unit tests and [react-testing-library](https://testing-library.com/docs/react-testing-library/intro) for rendering and writing assertions. Please make sure you include tests with your pull requests. Our CI will run the tests on PRs as well as the linter and type checker. You can see on each PR whether you have passed all our checks. We split the tests into 2 groups.
108
130
109
-
*Visual tests*
131
+
_Visual tests_
132
+
110
133
- A Storybook story should be written for each visual state that a component can be in (based on props).
111
134
112
-
*Unit tests*
135
+
_Unit tests_
136
+
113
137
- (Props) Anything that should be changed by a prop should be tested via react-testing-library.
114
138
- (Events) Anything that should trigger an event should be tested via react-testing-library.
115
139
@@ -126,50 +150,65 @@ yarn jest --coverage
126
150
```
127
151
128
152
### Linting
153
+
129
154
The code is linted with [eslint](https://eslint.org/). The linter runs whenever you run the tests, but you can also run it with
155
+
130
156
```bash
131
157
yarn lint
132
158
```
133
159
134
160
### TypeScript
161
+
135
162
The code for React Spectrum is written in [TypeScript](https://www.typescriptlang.org/). The type checker will usually run in your editor, but also runs when you run
163
+
136
164
```bash
137
165
yarn lint
138
166
```
139
167
140
168
### Storybook
169
+
141
170
We use [Storybook](https://storybooks.js.org) for local development. Run the following command to start it:
171
+
142
172
```bash
143
173
yarn start
144
174
```
175
+
145
176
Then, open [http://localhost:9003](http://localhost:9003) in your browser to play around with the components and test your changes.
146
177
147
178
### Documentation
179
+
148
180
Our documentation should always remain up to date. When making changes to components, make sure the appropriate documentation has been updated to reflect those changes. Documentation for each component can be found in the docs folder within a component's package. Other documentation pages can be found in the [packages/dev/docs](https://github.com/adobe/react-spectrum/tree/main/packages/dev/docs) folder in the codebase.
149
181
150
182
Documentation can be run locally by using
183
+
151
184
```bash
152
185
yarn start:docs
153
186
```
187
+
154
188
Then, open [http://localhost:1234](http://localhost:1234) in your browser.
155
189
156
190
### Verdaccio
157
-
We use [Verdaccio](https://verdaccio.org/) to set up a private registry for our packages to test our components in our example apps.
191
+
192
+
We use [Verdaccio](https://verdaccio.org/) to set up a private registry for our packages to test our components in our example apps.
158
193
159
194
To run verdaccio, first ensure that your `git status` is clean. If your computer has an Intel chip, add the line `shopt -s globstar extglob` in the `verdaccio.sh` file after line 21. Save and commit these changes under a clear message like "Do not push". If you have an Apple silicon chip, you may skip this step.
160
195
161
196
Then, run the following command:
197
+
162
198
```bash
163
199
./scripts/verdaccio.sh
164
200
```
165
201
166
202
Once that is finished, open up a new terminal and change your directory to the example app you would like to test. You may test it by first running the command:
203
+
167
204
```bash
168
205
yarn install
169
206
```
207
+
170
208
And then the appropriate command to run the development server. Check the project's `package.json` for the correct command.
171
209
172
210
If you are running into issues with `yarn install` at this step, you may need to clear your yarn cache. To do this, run this following command:
211
+
173
212
```
174
213
rm -r ~/.yarn/berry/metadata/npm
175
214
yarn cache clean --all
@@ -209,7 +248,7 @@ It's likely that you are using a different version of Node.js. Please use Node.j
209
248
For example:
210
249
211
250
```
212
-
@parcel/core: packages/@react-aria/virtualizer/src/index.ts does not export 'useVirtualizer'
251
+
@parcel/core: packages/@react-aria-nutrient/virtualizer/src/index.ts does not export 'useVirtualizer'
213
252
```
214
253
215
254
You may have run `yarn build` before. Please run `make clean_all && yarn` to clean up the build artifacts.
0 commit comments