|
|
@@ -0,0 +1,39 @@
|
|
|
+Contributing
|
|
|
+===
|
|
|
+
|
|
|
+Organization
|
|
|
+---
|
|
|
+
|
|
|
+Source is contained in the `src` directory. There is roughly one Lua file for each class, though the operators are stored in their own files in the `src/operators` directory.
|
|
|
+
|
|
|
+Tooling
|
|
|
+---
|
|
|
+
|
|
|
+There are a number of scripts in the `tools` folder that automate certain tasks. In general, they are run using `lua tools/<file>.lua` from the project root and take no arguments.
|
|
|
+
|
|
|
+- Everything in the `src` directory is concatenated into a single `rx.lua` file in the project root. The file `tools/concat.lua` does this concatenation. It strips out both the requires at the top of files and the return values at the bottom.
|
|
|
+- The documentation in `doc/README.md` is automatically generated based on comments in the source. The file `tools/update_documentation.lua` performs this generation. Internally it uses `docroc`, which is a library that parses Lua comments and returns them in a table. From here, `update_documentation` converts the table to markdown and writes it to the `doc` directory.
|
|
|
+- Currently, you should run both of these scripts and include an updated `rx.lua` and `doc/README.md` as part of a pull request. If you've added a new file you'll have to add it (alphabetized) to the file list in `tools/concat.lua`.
|
|
|
+
|
|
|
+Tests
|
|
|
+---
|
|
|
+
|
|
|
+- Tests are recommended when adding new functionality. The reason is that they demonstrate correct behavior, provide a form of documentation, and protect against future bugs.
|
|
|
+- RxLua uses [lust](https://github.com/bjornbytes/lust) for testing.
|
|
|
+- To run the tests, run `lua tests/runner.lua` from the project root.
|
|
|
+- To run a specific test file, run `lua tests/runner.lua average` to just run the tests in `tests/average.lua`.
|
|
|
+- In addition to lust's default operators, there are also a few additional utilities available via `runner.lua`:
|
|
|
+ - `expect(Observable).to.produce(...)` will assert that the Observable produces the specified values, in order. If you need to assert against multiple values emitted by a single `onNext`, you can pass in a table (i.e. `{{1, 2, 3}, {4, 5, 6}}` to check that an Observable calls `onNext` twice with 3 values each).
|
|
|
+ - There is also `expect(Observable).to.produce.nothing()`.
|
|
|
+ - `local onNext, onError, onCompleted = observableSpy(observable)` will create three spies for each of the three events. You can read more about spies on lust's README.
|
|
|
+
|
|
|
+Style
|
|
|
+---
|
|
|
+
|
|
|
+Aim for a consistent style.
|
|
|
+
|
|
|
+- Wrap lines to 100 characters.
|
|
|
+- Indent using two spaces.
|
|
|
+- Document functions using `docroc` syntax so documentation gets automatically generated. In general this means starting your first comment with three dashes, then using `@arg` and `@returns`.
|
|
|
+- Tend to avoid single line `if`s (i.e. `if condition then action end`).
|
|
|
+- Ensure each file ends in a single trailing newline with no extra blank lines. This helps with ensuring the base `rx.lua` file gets concatenated correctly.
|
Bjorn Swenson