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.
12## Developer documentation
14Build haddock with the `--show-all` option to see the documentation for all
15modules including the ones not exposed to users of the library.
17`stack haddock --haddock-arguments "--show-all" --no-haddock-deps`.
21Please feel free to [send a pull
22request (PR)](https://github.com/composewell/streamly/pulls) whether it is a single
23letter typo fix in documentation or a more complex change. If the feature makes
24significant changes to design, we encourage you to open an issue as early as
25possible so that you do not have to redo much work because of changes in design
26decisions. However, if you are confident, you can still go ahead and take that
29### Picking Issues to Work on
31Beginners are encouraged to pick up issues that are marked `help wanted`.
35* Please make sure that a single PR contains a single logical changeset. That
36 helps the reviewers in quickly understanding and reviewing the change.
37* You are encouraged to group a logically related set of changes into a single
38 commit. When the overall changeset is largish you can divide it into
39 multiple smaller commits, with each commit having a logically grouped
40 changeset and the title summarizing the logical grouping. Always keep in
41 mind a logical division helps reviewers understand and review your code
42 quickly, easier history tracking and when required clean reversal changes.
43* If your commits reflect how you fixed intermediate problems during testing
44 or made random changes at different times you may have to squash your changes
45 (`git rebase -i`) into a single commit or logically related set of commits.
46* Please resist the temptation to make style related changes to surrounding
47 code unless you are changing that code anyway . Make sure that your
48 IDE/Editor is not automatically making sweeping style changes to all the
49 files you are editing. That makes separating the signal from the noise
50 very difficult and makes everything harder. If you would like to make style
51 related changes then please send a separate PR with just those changes and no
52 other functionality changes.
54### Resolving Conflicts
56If during the course of development or before you send the PR you find that
57your changes are conflicting with the master branch then use `git rebase
58master` to rebase your changes on top of master. DO NOT MERGE MASTER INTO YOUR
63It is a good idea to include tests for the changes where applicable.
67For user visible APIs, it is a good idea to provide haddock documentation that
68is easily understood by the end programmer and does not sound highfalutin,
69and preferably with examples.
71### Performance Benchmarks
73It is a good idea to run performance benchmarks to see if your change affects
74any of the existing performance benchmarks. If you introduced something new
75then you may want to add benchmarks to check if it performs as well as expected
76by the programmers to deem it usable.
80Any new changes that affect the user of the library in some way must be
81documented under `Unreleased` section at the top of the `Changelog`. The
82changes in the changelog must be organized in the following categories, in that
90If there are very few changes then you can just prefix a bullet with these
91annotations. If there are many changes make sections to group them. A section
92can be absent if there is nothing to add in it.
94If you make changes that are incompatible with the released versions
95of the library please indicate that in the `Changelog` as `Breaking Changes`
96and also write short notes regarding what the programmers need to do to adapt
97their existing code to the new change.
103As long as possible please try to match the style of the file or the
104surrounding code. For haskell coding style guidelines, please [see this style
105guide](https://github.com/tibbe/haskell-style-guide/blob/master/haskell-style.md).
108* Please use 4 spaces for indentation.
109* Do not let the code go beyond 80 columns
113Use this simple rule to organize functions in a file: `Define before first
114use`. In other words, use the `bottom up style` to organize functions.
116One big benefit of this rule is easier type error debugging. Using a single
117block comment, at any point in the file up to the end of the file, you can cut
118the tail and still cleanly compile the remaining head portion of the file.
120It is very helpful when we make significant changes to the file. We can start
121compiling a minimal head portion of the file and keep expanding the head by
122just moving the start of commented block further down. This keeps the scope of
123type inference minimal and type errors can be discovered incrementally by
124increasing the scope a little bit at a time. If you use type signatures on all
125top level declarations then you do not even need to comment out the code. This
126organization results in a better order of type errors which makes it easier to
127fix them and when necessary use elimination method by commenting out some code.
129Similarly when you put modules in the cabal file in dependency order you can
130do the same there, just comment out a tail of the module list and your library
133Note that this rule does not apply in choosing `let` vs `where` clauses. Use of
134`let`s leads to bottom up and use of `where`s leads to top down style. But we
135do not encourage `let` over `where`, you can freely use `where` clauses.
137Also note that this is not possible in mutually recursive code. The mutually
138recursive code has to be considered a single block.
142The state-passing through each API is currently fragile. Every time we run a
143stream we need to be careful about the state we are passing to it. In case of
144folds where there is no incoming state, we start with the initial state
145`defState`. When we have an incoming state passed to us there are two cases:
1471. When we are building a concurrent stream that needs to share the same `SVar`
148 we pass the incoming state as is.
1492. In all other cases we must not share the SVar and everytime we pass on the
150 state to run a stream we must use `rstState` to reset the `SVar` in the
153When in doubt just use `rstState` on the state before passing it on, we will at
154most lose concurrency but the behavior will be correct.
156There is no type level enforcement about this as of now, and therefore we need
157to be careful when coding. There are specific tests to detect and report any
158problems 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