@@ -0,0 +1,97 @@
1+# Contributors' Guide
2+
3+## Bug Reports
4+
5+Please feel free to [open an
6+issue](https://github.com/composewell/streamly/issues) for any questions,
7+suggestions, issues or bugs in the library. In case you are reporting a bug
8+we will appreciate if you provide as much detail as possible to reproduce or
9+understand the problem, but nevertheless you are encouraged to open an issue
10+for any problem that you may encounter.
11+
12+## Pull Requests (PR)
13+
14+Please feel free to [send a pull
15+request (PR)](https://github.com/composewell/streamly/pulls) whether it is a single
16+letter typo fix in documentation or a more complex change. If the feature makes
17+significant changes to design, we encourage you to open an issue as early as
18+possible so that you do not have to redo much work because of changes in design
19+decisions. However, if you are confident, you can still go ahead and take that
20+risk.
21+
22+### Picking Issues to Work on
23+
24+Beginners are encouraged to pick up issues that are marked `help wanted`.
25+
26+### Changeset in a PR
27+
28+* Please make sure that a single PR contains a single logical changeset. That
29+ helps the reviewers in quickly understanding and reviewing the change.
30+* You are encouraged to group a logically related set of changes into a single
31+ commit. When the overall changeset is largish you can divide it into
32+ multiple smaller commits, with each commit having a logically grouped
33+ changeset and the title summarizing the logical grouping. Always keep in
34+ mind a logical division helps reviewers understand and review your code
35+ quickly, easier history tracking and when required clean reversal changes.
36+* If your commits reflect how you fixed intermediate problems during testing
37+ or made random changes at different times you may have to squash your changes
38+ (`git rebase -i`) into a single commit or logically related set of commits.
39+* Please resist the temptation to make style related changes to surrounding
40+ code unless you are changing that code anyway . Make sure that your
41+ IDE/Editor is not automatically making sweeping style changes to all the
42+ files you are editing. That makes separating the signal from the noise
43+ very difficult and makes everything harder. If you would like to make style
44+ related changes then please send a separate PR with just those changes and no
45+ other functionality changes.
46+
47+### Resolving Conflicts
48+
49+If during the course of development or before you send the PR you find that
50+your changes are conflicting with the master branch then use `git rebase
51+master` to rebase your changes on top of master. DO NOT MERGE MASTER INTO YOUR
52+BRANCH.
53+
54+### Testing
55+
56+It is a good idea to include tests for the changes where applicable.
57+
58+### Documentation
59+
60+For user visible APIs, it is a good idea to provide haddock documentation that
61+is easily understood by the end programmer and does not sound highfalutin,
62+and preferably with examples.
63+
64+### Performance Benchmarks
65+
66+It is a good idea to run performance benchmarks to see if your change affects
67+any of the existing performance benchmarks. If you introduced something new
68+then you may want to add benchmarks to check if it performs as well as expected
69+by the programmers to deem it usable.
70+
71+### Changelog
72+
73+If you make changes that are incompatible with the released versions of the
74+library please indicate that in the `Changelog` as `Breaking Changes` and what
75+the programmers need to do to adapt to the new change. Any new user visible
76+changes must be documented in the `Changelog`.
77+
78+## Coding Style
79+
80+As long as possible please try to match the style of the file or the
81+surrounding code.
82+
83+* Please use 4 spaces for indentation.
84+* Do not let the code go beyond 79 columns
85+* Use multiline `let` clauses like this:
86+ ```
87+ let stop = stp
88+ yield a Nothing = ...
89+ ...
90+ ```
91+* Align the contents of the where clause in the same column as the `where`
92+ keyword for saving unnecessary indentation, like this:
93+ ```
94+ where
95+
96+ x = ...
97+ ```