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
(This document is a work in progress and is subject to change)
34
35
35
36
## Submitting a Pull Request (PR)
37
+
36
38
Before you submit your Pull Request (PR) consider the following guidelines:
37
39
38
-
* Search [GitHub](https://github.com/ReactiveX/RxJS/pulls) for an open or closed PR
40
+
- Search [GitHub](https://github.com/ReactiveX/RxJS/pulls) for an open or closed PR
39
41
that relates to your submission. You don't want to duplicate effort.
40
-
* Make your changes in a new git branch:
42
+
- Make your changes in a new git branch:
41
43
42
-
```shell
43
-
git checkout -b my-fix-branch master
44
-
```
44
+
```shell
45
+
git checkout -b my-fix-branch master
46
+
```
45
47
46
-
* Create your patch, following [code style guidelines](#coding-style-guidelines), and **including appropriate test cases**.
47
-
* Run the full test suite and ensure that all tests pass.
48
-
* Run the micro and macro performance tests against your feature branch and compare against master
48
+
- Create your patch, following [code style guidelines](#coding-style-guidelines), and **including appropriate test cases**.
49
+
- Run the full test suite and ensure that all tests pass.
50
+
- Run the micro and macro performance tests against your feature branch and compare against master
49
51
to ensure performance wasn't changed for the worse.
50
-
* Commit your changes using a descriptive commit message that follows our
52
+
- Commit your changes using a descriptive commit message that follows our
51
53
[commit message guidelines](#commit-message-guidelines). Adherence to these conventions
52
54
is necessary because release notes are automatically generated from these messages.
53
55
54
-
```shell
55
-
git commit -a
56
-
```
56
+
```shell
57
+
git commit -a
58
+
```
59
+
57
60
Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files.
58
61
59
-
* Push your branch to GitHub:
62
+
- Push your branch to GitHub:
60
63
61
-
```shell
62
-
git push origin my-fix-branch
63
-
```
64
+
```shell
65
+
git push origin my-fix-branch
66
+
```
67
+
68
+
- In GitHub, send a pull request to `RxJS:master`.
69
+
- If we suggest changes then:
64
70
65
-
* In GitHub, send a pull request to `RxJS:master`.
66
-
* If we suggest changes then:
67
-
* Make the required updates.
68
-
* Re-run the test suites to ensure tests are still passing.
69
-
* Re-run performance tests to make sure your changes didn't hurt performance.
70
-
* Rebase your branch and force push to your GitHub repository (this will update your Pull Request):
71
+
- Make the required updates.
72
+
- Re-run the test suites to ensure tests are still passing.
73
+
- Re-run performance tests to make sure your changes didn't hurt performance.
74
+
- Rebase your branch and force push to your GitHub repository (this will update your Pull Request):
71
75
72
76
```shell
73
77
git rebase master -i
74
78
git push -f
75
79
```
76
80
77
-
* When updating your feature branch with the requested changes, please do not overwrite the commit history, but rather contain the changes in new commits. This is for the sake of a clearer and easier review process.
81
+
- When updating your feature branch with the requested changes, please do not overwrite the commit history, but rather contain the changes in new commits. This is for the sake of a clearer and easier review process.
78
82
79
83
That's it! Thank you for your contribution!
80
84
81
-
82
85
### After your pull request is merged
83
86
84
87
After your pull request is merged, you can safely delete your branch and pull the changes
85
88
from the main (upstream) repository:
86
89
87
-
* Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:
90
+
- Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:
88
91
89
-
```shell
90
-
git push origin --delete my-fix-branch
91
-
```
92
+
```shell
93
+
git push origin --delete my-fix-branch
94
+
```
92
95
93
-
* Check out the master branch:
96
+
- Check out the master branch:
94
97
95
-
```shell
96
-
git checkout master -f
97
-
```
98
+
```shell
99
+
git checkout master -f
100
+
```
98
101
99
-
* Delete the local branch:
102
+
- Delete the local branch:
100
103
101
-
```shell
102
-
git branch -D my-fix-branch
103
-
```
104
+
```shell
105
+
git branch -D my-fix-branch
106
+
```
104
107
105
-
* Update your master with the latest upstream version:
108
+
- Update your master with the latest upstream version:
106
109
107
-
```shell
108
-
git pull --ff upstream master
109
-
```
110
+
```shell
111
+
git pull --ff upstream master
112
+
```
110
113
111
114
## Coding Style Guidelines
112
115
@@ -121,15 +124,14 @@ from the main (upstream) repository:
121
124
- The documentation is auto-generated directly from the source code.
122
125
- In short: From the source code we generate JSON documents, describing each operator, function ... and render this JSON within an Angular application
123
126
- The folder `docs-app` contains everything you need for building and developing the docs
124
-
- the folder `doc` used to be the documentation, but should remain until all content is transferred.
125
127
- The [Documentation README](docs_app/README.md) will support you
126
128
- After a PR is merged to master the docs will be published to https://rxjs.dev/
127
129
128
130
## Unit Tests
129
131
130
132
Unit tests are located under the [spec directory](/spec). Unit tests over synchronous operators and operations
131
133
can be written in a standard [chai](https://www.chaijs.com/) style. Unit tests written against any
132
-
asynchronous operator should be written in [Marble Test Style outlined in detail here](doc/writing-marble-tests.md).
134
+
asynchronous operator should be written in [Marble Test Style outlined in detail here](doccs_app/content/guide/testing/internal-marble-tests.md).
133
135
134
136
Each operator under test must be in its own file to cover the following cases:
135
137
@@ -148,26 +150,26 @@ then it must cover the following cases:
148
150
- If an error is thrown
149
151
150
152
### CI Tests
153
+
151
154
- Using [Travis](https://travis-ci.org/) on your forked version of RxJS will allow running CI tests on that fork before submitting a PR to master
152
-
- Simply create a `Travis` account and add your fork as a new project
155
+
- Simply create a `Travis` account and add your fork as a new project
153
156
- [Sauce Labs](https://saucelabs.com/) setup will allow performing automated browser tests on the fork. Since `saucelabs` doesn't perform browser tests on a PR, this will help verify test results before PR's are checked into master.
154
-
- In your `Travis` repo configuration, set the environment variables SAUCE_USERNAME and SAUCE_ACCESS_KEY to your `saucelabs` account ([reference](https://cloud.githubusercontent.com/assets/1210596/12679038/b9ba4eb6-c656-11e5-8c9b-b063c9a3f9dc.png))
157
+
- In your `Travis` repo configuration, set the environment variables SAUCE_USERNAME and SAUCE_ACCESS_KEY to your `saucelabs` account ([reference](https://cloud.githubusercontent.com/assets/1210596/12679038/b9ba4eb6-c656-11e5-8c9b-b063c9a3f9dc.png))
155
158
- As master runs both of these tests per each check in, it'd be welcome to setup those test before creating your PR
156
159
157
160
## Performance Tests
158
161
159
162
One of the primary goals of this library is (and will continue to be) great performance. As such, we've employed a variety of performance
160
163
testing techniques.
161
164
162
-
- DON'T labor over minute variations in ops/sec or milliseconds, there will always be variance in perf test results.
163
-
- DON'T alter a performance test unless absolutely necessary. Performance tests may be compared to previous results from previous builds.
164
-
- DO run tests multiple times and make sure the margins of error are low
165
-
- DO run tests in your feature branches and compare them to master
166
-
- DO add performance tests for all new operators
167
-
- DO add performance tests that you feel are missing from other operators
168
-
- DO add additional performance tests for all worthy code paths. If you develop an operator with special handling for scalar observables,
169
-
please add tests for those scenarios
170
-
165
+
- DON'T labor over minute variations in ops/sec or milliseconds, there will always be variance in perf test results.
166
+
- DON'T alter a performance test unless absolutely necessary. Performance tests may be compared to previous results from previous builds.
167
+
- DO run tests multiple times and make sure the margins of error are low
168
+
- DO run tests in your feature branches and compare them to master
169
+
- DO add performance tests for all new operators
170
+
- DO add performance tests that you feel are missing from other operators
171
+
- DO add additional performance tests for all worthy code paths. If you develop an operator with special handling for scalar observables,
172
+
please add tests for those scenarios
171
173
172
174
### Macro
173
175
@@ -187,7 +189,6 @@ npm run build_all
187
189
protractor protractor.conf.js
188
190
```
189
191
190
-
191
192
### Micro
192
193
193
194
[Micro performance tests](perf/micro) really only serve to test operations per second. They're quick and easy to develop, and provide a reasonable look into the
@@ -208,13 +209,14 @@ node perf/micro zip
208
209
209
210
## Commit Message Guidelines
210
211
211
-
We have very precise rules over how our git commit messages can be formatted. This leads to **more
212
+
We have very precise rules over how our git commit messages can be formatted. This leads to **more
212
213
readable messages** that are easy to follow when looking through the **project history**. But also,
213
214
we use the git commit messages to **generate the RxJS change log**. Helper script `npm run commit`
214
215
provides command line based wizard to format commit message easily.
215
216
216
217
### Commit Message Format
217
-
Each commit message consists of a **header**, a **body** and a **footer**. The header has a special
218
+
219
+
Each commit message consists of a **header**, a **body** and a **footer**. The header has a special
218
220
format that includes a **type**, a **scope** and a **subject**:
219
221
220
222
```
@@ -231,38 +233,44 @@ Any line of the commit message cannot be longer than 100 characters! This allows
231
233
to read on GitHub as well as in various git tools.
232
234
233
235
### Revert
234
-
If the commit reverts a previous commit, it should begin with `revert: `, followed by the header of the reverted commit. In the body it should say: `This reverts commit <hash>.`, where the hash is the SHA of the commit being reverted.
236
+
237
+
If the commit reverts a previous commit, it should begin with `revert:`, followed by the header of the reverted commit. In the body it should say: `This reverts commit <hash>.`, where the hash is the SHA of the commit being reverted.
235
238
236
239
### Type
240
+
237
241
Must be one of the following:
238
242
239
-
***feat**: A new feature
240
-
***fix**: A bug fix
241
-
***docs**: Documentation only changes
242
-
***style**: Changes that do not affect the meaning of the code (white-space, formatting, missing
243
+
- **feat**: A new feature
244
+
- **fix**: A bug fix
245
+
- **docs**: Documentation only changes
246
+
- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing
243
247
semi-colons, etc)
244
-
***refactor**: A code change that neither fixes a bug nor adds a feature
245
-
***perf**: A code change that improves performance
246
-
***test**: Adding missing tests
247
-
***chore**: Changes to the build process or auxiliary tools and libraries such as documentation
248
+
- **refactor**: A code change that neither fixes a bug nor adds a feature
249
+
- **perf**: A code change that improves performance
250
+
- **test**: Adding missing tests
251
+
- **chore**: Changes to the build process or auxiliary tools and libraries such as documentation
248
252
generation
249
253
250
254
### Scope
255
+
251
256
The scope could be anything specifying the place of the commit change. For example
252
257
`Observable`, `Subject`, `switchMap`, etc.
253
258
254
259
### Subject
260
+
255
261
The subject contains succinct description of the change:
256
262
257
-
* use the imperative, present tense: "change" not "changed" nor "changes"
258
-
* don't capitalize first letter
259
-
* no dot (.) at the end
263
+
- use the imperative, present tense: "change" not "changed" nor "changes"
264
+
- don't capitalize first letter
265
+
- no dot (.) at the end
260
266
261
267
### Body
268
+
262
269
Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes".
263
270
The body should include the motivation for the change and contrast this with previous behavior.
264
271
265
272
### Footer
273
+
266
274
The footer should contain any information about **Breaking Changes** and is also the place to
267
275
reference GitHub issues that this commit **Closes**.
It's recommended to pull in the Observable creation methods you need directly from `'rxjs'` as shown below with `range`. And you can pull in any operator you need from one spot, under `'rxjs/operators'`.
43
40
44
41
```ts
45
-
import { range } from'rxjs';
46
-
import { map, filter } from'rxjs/operators';
47
-
48
-
range(1, 200).pipe(
49
-
filter(x=>x%2===1),
50
-
map(x=>x+x)
51
-
).subscribe(x=>console.log(x));
42
+
import { range } from"rxjs";
43
+
import { map, filter } from"rxjs/operators";
44
+
45
+
range(1, 200)
46
+
.pipe(
47
+
filter(x=>x%2===1),
48
+
map(x=>x+x)
49
+
)
50
+
.subscribe(x=>console.log(x));
52
51
```
53
52
54
53
### CDN
@@ -63,10 +62,12 @@ The global namespace for rxjs is `rxjs`:
63
62
const { range } = rxjs;
64
63
const { map, filter } =rxjs.operators;
65
64
66
-
range(1, 200).pipe(
67
-
filter(x=> x %2===1),
68
-
map(x=> x + x)
69
-
).subscribe(x=>console.log(x));
65
+
range(1, 200)
66
+
.pipe(
67
+
filter(x=> x %2===1),
68
+
map(x=> x + x)
69
+
)
70
+
.subscribe(x=>console.log(x));
70
71
```
71
72
72
73
## Goals
@@ -90,4 +91,5 @@ Run `npm run build_perf` or `npm run perf` to run the performance tests with `pr
90
91
Run `npm run perf_micro [operator]` to run micro performance test benchmarking operator.
91
92
92
93
## Adding documentation
94
+
93
95
We appreciate all contributions to the documentation of any type. All of the information needed to get the docs app up and running locally as well as how to contribute can be found in the [documentation directory](./docs_app).
0 commit comments