5Please feel free to [open an
6issue](https://github.com/composewell/streamly/issues) for any questions,
7suggestions, issues or bugs in the library. In case you are reporting a bug
8we will appreciate if you provide as much detail as possible to reproduce or
9understand the problem, but nevertheless you are encouraged to open an issue
10for any problem that you may encounter.
14Please feel free to [send a pull
15request (PR)](https://github.com/composewell/streamly/pulls) whether it is a
16single letter typo fix or a complex change. We will accept any PR that makes a
17net positive change to the package. We encourage you to provide a complete,
18consistent change with test, documentation and benchmarks. You can contact the
19[maintainers](https://gitter.im/composewell/streamly) for any help or
20collaboration needed in that regard. However, if due to lack of time you are
21not able to complete the PR, you are still welcome to submit it, maintainers
22will try their best to actively contribute and pick up your change as long as
23the change is approved.
25## Pull Request (PR) Checklist
27Here is a quick checklist for a PR, for details please see the next section:
29* PR contains one logical changeset
30* Each commit in the PR consists of a logical change
31* Commits are rebased/squashed/fixup/reordered as needed
32* Stylistic changes to irrelevant parts of the code are separated in
34* Code is formatted as per the style of the file or that of other files
35* Compiler warnings are fixed
36* Reasonable hlint suggestions are accepted
37* Tests are added to cover the changed parts
38* All [tests](test) pass
39* [Performance benchmarks](benchmark) are added, where applicable
40* No significant regressions are reported by [performance benchmarks](benchmark/README.md)
41* Haddock documentation is added to user visible APIs and data types
42* Tutorial module, [README](README.md), and [guides](docs) are updated if
44* [Changelog](Changelog.md) is updated if needed
46## Contributing A Change
48If the feature makes significant changes to design, we encourage you to open an
49issue as early as possible so that you do not have to redo much work because of
50changes in design decisions. However, if you are confident, you can still go
51ahead and take that risk as the maintainers are supposed to be reasonable
54### Picking Issues to Work on
56Beginners are encouraged to pick up issues that are marked `help wanted`. It is
57a good idea to update the issue expressing your intent so that others do not
58duplicate the effort and people with a background on the issue can help.
62* Please make sure that a single PR contains a single logical changeset. That
63 helps the reviewers in quickly understanding and reviewing the change.
64* You are encouraged to group a logically related set of changes into a single
65 commit. When the overall changeset is largish you can divide it into
66 multiple smaller commits, with each commit having a logically grouped
67 changeset and the title summarizing the logical grouping. Always keep in
68 mind a logical division helps reviewers understand and review your code
69 quickly, easier history tracking and when required clean reversal changes.
70* If your commits reflect how you fixed intermediate problems during testing
71 or made random changes at different times you may have to squash your changes
72 (`git rebase -i`) into a single commit or logically related set of commits.
73* Please resist the temptation to make style related changes to surrounding
74 code unless you are changing that code anyway . Make sure that your
75 IDE/Editor is not automatically making sweeping style changes to all the
76 files you are editing. That makes separating the signal from the noise
77 very difficult and makes everything harder. If you would like to make style
78 related changes then please send a separate PR with just those changes and no
79 other functionality changes.
81### Resolving Conflicts
83If during the course of development or before you send the PR you find that
84your changes are conflicting with the master branch then use `git rebase
85master` to rebase your changes on top of master. DO NOT MERGE MASTER INTO YOUR
90It is a good idea to include tests for the changes where applicable. See the
91existing tests [here](test).
95For user visible APIs, it is a good idea to provide haddock documentation that
96is easily understood by the end programmer and does not sound highfalutin,
97and preferably with examples. If your change affects the tutorial or needs to
98be mentioned in the tutorial then please update the tutorial. Check if the
99additional [guides](docs) are affected or need to updated.
101### Performance Benchmarks
103It is a good idea to run performance benchmarks to see if your change affects
104any of the existing performance benchmarks. If you introduced something new
105then you may want to add benchmarks to check if it performs as well as expected
106by the programmers to deem it usable.
108See the [README](benchmark/README) file in the `benchmark` directory for more
109details on how to run the benchmarks.
111The first level of check is the regression in "allocations", this is
112the most stable measure of regression. "bytesCopied" is another stable
113measure, it gives an idea of the amount of long lived data being copied
114across generations of GC.
116The next measure to look at is "cpuTime" this may have some variance
117from run to run because of factors like cpu frequency scaling, load on
118the system or the number of context switches etc. However, the variance
119would usually be within 5-10%, anything more than that is likely to be a
122Quite often an increase in "cpuTime" would correspond to an increase
123in "allocations". Increase in "allocations" indicates an inefficiency
124in computing due to too much GC activity e.g. due to lack of
125fusion. However, it is also possible for the cpu time to go up without
126the allocations going up, this indicates an inefficiency in processing
127in general or more CPU being used for the same task. It could be because
128of inefficient code generation, branch mis-predictions or lack of cache
131For concurrent benchmarks we can compare "cpuTime" and "time" to check
132the degree of concurrency and total efficiency.
136Any new changes that affect the user of the library in some way must be
137documented under `Unreleased` section at the top of the `Changelog`. The
138changes in the changelog must be organized in the following categories, in that
146If there are very few changes then you can just prefix a bullet with these
147annotations. If there are many changes make sections to group them. A section
148can be absent if there is nothing to add in it.
150If you make changes that are incompatible with the released versions
151of the library please indicate that in the `Changelog` as `Breaking Changes`
152and also write short notes regarding what the programmers need to do to adapt
153their existing code to the new change.
155## Developer documentation
157To build haddock documentation for all modules, including the ones not exposed
158to users of the library, use the following commands:
162$ stack haddock --no-haddock-deps
165For design documentation see the `design` directory.
171Please see [the Haskell coding style guide](https://github.com/composewell/haskell-dev/blob/master/coding-style.rst).
173### StreamD coding style
175Some conventions that we follow in the StreamD code are illustrated by the
179mapM f (Stream step1 state1) = Stream step state
183 r <- step1 (adaptState gst) st
185 Yield x s -> f x >>= \a -> return $ Yield a s
186 Skip s -> return $ Skip s
190* For the input streams use numbering for `step` and `state` e.g.
191 step1/state1. For the output stream use `step` and `state`.
192* For state argument of `step`, use `st`.
193* For result of executing a `step` use `r` or `res`
194* For the yielded element use `x`
195* For the yielded state use `s`
197In general, the rule is - the shorter the scope of a variable the shorter its
198name can be. For example, `s` has the shortest scope in the above code, `st`
199has a bigger scope and `state` has the biggest scope.
201For better fusion we try to keep a single yield point in the state machine.
205The state-passing through each API is currently fragile. Every time we run a
206stream we need to be careful about the state we are passing to it. In case of
207folds where there is no incoming state, we start with the initial state
208`defState`. When we have an incoming state passed to us there are two cases:
2101. When we are building a concurrent stream that needs to share the same `SVar`
211 we pass the incoming state as is.
2122. In all other cases we must not share the SVar and every time we pass on the
213 state to run a stream we must use `adaptState` to reset the `SVar` in the
216When in doubt just use `adaptState` on the state before passing it on, we will at
217most lose concurrency but the behavior will be correct.
219There is no type level enforcement about this as of now, and therefore we need
220to be careful when coding. There are specific tests to detect and report any
221problems due to this, all transform operations must be added to those tests.
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list