| 1 | First of all, thank you for contributing. It’s appreciated.
|
| 2 |
|
| 3 | # Design goals
|
| 4 |
|
| 5 | I invite you first to read these design goals. If a PR is rejected, it's on the basis of these goals. Having a PR rejected is a horrible feeling, so before doing work in vain I want to help you understand what defines the xstream codebase.
|
| 6 |
|
| 7 | xstream's goal is to provide a **beginner-friendly foundation for reactive programming**.
|
| 8 |
|
| 9 | - **Beginner-friendly** means:
|
| 10 | - It has core operators and extra operators so that the core operators are seen as fundamental building blocks while extra operators exist to support less-common use cases
|
| 11 | - It must have few operators (either core or extra) to reduce decision paralysis
|
| 12 | - Naming is important to hint what is common and what is rare or wrong. Shorter names mean more common usage, and longer names mean more rare usage. For instance `flatten` is more common to use than `flattenSequentially`, so the former has a shorter name than the latter. Also `shamefullySendNext` is a "bad" use case so it has a bad name too.
|
| 13 | - Hot behavior only since it matches people's intuition of a "stream" better
|
| 14 | - RefCount with sync start and async stop to support both "shared execution" and "laziness" properties
|
| 15 | - **Foundation** means:
|
| 16 | - It must be small, its size must float around 4kB minified+gzipped
|
| 17 | - It must be fast (enough), competitive with the state of the art reactive programming for JS
|
| 18 | - **Reactive programming** means:
|
| 19 | - Stream-based programming like in RxJS and most.js
|
| 20 |
|
| 21 | To achieve those above, xstream **sacrifices codebase readability**. We apply hard-coded minification techniques to keep the size as small as possible. A PR to improve readability will be **rejected** if the overall size increases. A PR to improve readability will be **rejected** if it makes the performance slower.
|
| 22 |
|
| 23 | Other reasons why a PR could be rejected:
|
| 24 |
|
| 25 | - Adding a core operator. **Please** open an issue to discuss this before doing any work.
|
| 26 | - Rename or change the API.
|
| 27 | - Adding user-friendly runtime warnings. Because these would affect code size. We rely on TypeScript to provide type mismatch errors. We are considering adding a development flag for runtime warnings, but we will not accept runtime warnings in production, as this would hurt xstream's "foundation" property.
|
| 28 |
|
| 29 | Note that all of these instructions above are to help you in not doing work in vain. We don't want you to get frustrated trying to contribute to open source.
|
| 30 |
|
| 31 | # To submit a pull request
|
| 32 |
|
| 33 | 1. Open a GitHub issue before doing significant amount of work.
|
| 34 | 2. Clone the repo. If it was already cloned, then git pull to get the latest from master.
|
| 35 | 4. Run `npm install` before anything else, and wait.
|
| 36 | 5. Write code.
|
| 37 | 6. Run `npm test` to lint and test. Don’t commit before fixing all errors and warnings.
|
| 38 | 7. **Commit using `npm run commit` and follow the CLI instructions.** (important!)
|
| 39 | 8. Make a pull request.
|
| 40 |
|
| 41 | # To release new versions
|
| 42 |
|
| 43 | You only need to do this if you are an author/publisher of this package.
|
| 44 |
|
| 45 | 1. Check that you have npm publishing rights before anything else.
|
| 46 | 2. Run `npm run check-release`.
|
| 47 | 3. Run `npm run release`.
|