@@ -15,6 +15,43 @@ Beginners are encouraged to pick up issues that are marked `help wanted`. It is
1515a good idea to update the issue expressing your intent so that others do not
1616duplicate the effort and people with a background on the issue can help.
1717
18+## Build and test
19+
20+Some common commands:
21+
22+```
23+$ cabal repl
24+$ cabal build
25+$ cabal build --disable-optimization --flags -opt
26+$ bin/test.sh --quick
27+$ bin/bench.sh --quick # For nix use "--use-nix"
28+$ bin/run-ci --targets help # Only supported with nix
29+$ cabal haddock
30+$ cabal-docspec --timeout 60 --check-properties --property-variables xs
31+```
32+
33+The `bin/test.sh` and `bin/bench.sh` are custom scripts to perform test
34+and benchmarking tasks conveniently. They support running a group of
35+tests or benchmarks, coverage, using correct optimization flags for
36+benchmarking, benchmark comparison reports etc. Use the `--help` option
37+to see how to use these. See [benchmark/README.md](benchmark/README.md)
38+and [test/README.md](test/README.md) for more details.
39+
40+You can also run tests or benchmarks directly for example:
41+
42+```
43+$ cabal test --disable-optimization --flags -opt --test-show-details=streaming --test-option=--color streamly-tests
44+```
45+
46+To view haddock docs open the link printed at the end of the haddock
47+command, in your browser.
48+
49+Nix users: There is a `default.nix` available which can be used to start
50+a nix-shell and then use the above commands as usual. nix-shell started
51+by `default.nix` creates a `.cabal.nix` for cabal configuration and sets
52+`CABAL_DIR` environment variable to point to that. Therefore, `~/.cabal`
53+would not be used.
54+
1855## Contributing A Change
1956
2057If the feature makes significant changes to design, we encourage you to open an
@@ -107,8 +144,9 @@ BRANCH.
107144
108145### Testing
109146
110−It is a good idea to include tests for the changes where applicable. See the
111−existing tests [here](test).
147+It is a good idea to include tests for the changes where applicable. See
148+the existing tests in the [test](test) directory. Also see the
149+[test/README](test/README) for more details on how to run the tests.
112150
113151### Documentation
114152
@@ -182,16 +220,9 @@ copying does not have an associated license please do not use it.
182220
183221## Developer documentation
184222
185−To build haddock documentation:
186−
187−```
188−$ cabal haddock
189−```
190−
191−Open the link printed at the end of the output of this command, in
192−your browser.
193−
194−For general library developer documentation see the `dev` directory.
223+* Use https://streamly.composewell.com/ for searching in reference docs
224+* Build haddock docs for latest reference docs
225+* See [the dev directory](dev) for design guidelines and dev documents.
195226
196227## Coding Guidelines
197228
@@ -239,27 +270,3 @@ mapM f (Stream step1 state1) = Stream step state
239270In general, the rule is - the shorter the scope of a variable the shorter its
240271name can be. For example, `s` has the shortest scope in the above code, `st`
241272has a bigger scope and `state` has the biggest scope.
242−
243−## Design guides
244−
245−See [the design directory](design) for design guidelines and documents.
246−
247−### Tricky Parts
248−
249−The state-passing through each API is currently fragile. Every time we run a
250−stream we need to be careful about the state we are passing to it. In case of
251−folds where there is no incoming state, we start with the initial state
252−`defState`. When we have an incoming state passed to us there are two cases:
253−
254−1. When we are building a concurrent stream that needs to share the same `SVar`
255− we pass the incoming state as is.
256−2. In all other cases we must not share the SVar and every time we pass on the
257− state to run a stream we must use `adaptState` to reset the `SVar` in the
258− state.
259−
260−When in doubt just use `adaptState` on the state before passing it on, we will at
261−most lose concurrency but the behavior will be correct.
262−
263−There is no type level enforcement about this as of now, and therefore we need
264−to be careful when coding. There are specific tests to detect and report any
265−problems due to this, all transform operations must be added to those tests.