|
1 |
| -# Contributing to io-sim |
| 1 | +# Building |
| 2 | + |
| 3 | +The project is build with `cabal-install`. You might need to run `cabal |
| 4 | +update` after cloning the repository (to update [`Cardano Haskell |
| 5 | +Packages`][CHaP] (`ChaP`) index). |
| 6 | + |
| 7 | +# Design Principles |
2 | 8 |
|
3 | 9 | We designed `io-classes` to be as close as possible to what `base` package
|
4 | 10 | provides. Almost all `IO` instances instantiate with api provided by one of
|
5 | 11 | the core packages, see
|
6 | 12 | [example](https://github.com/input-output-hk/io-sim/blob/main/io-classes/src/Control/Monad/Class/MonadSTM.hs?plain=1#L410-L446).
|
7 | 13 | Please keep this in mind when adding new functionality.
|
8 | 14 |
|
9 |
| -## Style Guide |
| 15 | +# Using in your project |
10 | 16 |
|
11 |
| -Please follow the [style guide][style-guide]. |
| 17 | +Currently the package is published to [`CHaP`][CHaP]. In future it will be |
| 18 | +published to `Hackage`. If you want to pull it from [`CHaP`][CHaP], this is |
| 19 | +relatively easy to setup; for example, checkout the |
| 20 | +[`cabal.project`](https://github.com/input-output-hk/typed-protocols/blob/master/cabal.project) |
| 21 | +file. Alternatively, you can relay on `source-repository-package` stanza in |
| 22 | +a `cabal.project` file. |
12 | 23 |
|
13 |
| -## Pull Request |
| 24 | +# Testing |
14 | 25 |
|
15 |
| -Ideally the series of commits you want to include should be written with the |
16 |
| -reviewer in mind. This will make it easier for the maintainers to review your |
17 |
| -changes. Each commit should heave a clear explanation what it changes and most |
18 |
| -importantly why the changes are necessary. We prefer if commits are small and |
19 |
| -just introduce a single change. For example if you are adding a new typeclass |
20 |
| -in `io-classes` and you want `io-sim` and `io-sim-por` to support it, we'd |
21 |
| -expect at least three commits: first which introduces the new type class, and |
22 |
| -separate commits which add implement it for `IOSim` and `IOSimPOR`, since both |
23 |
| -are using the same free monad, just interpret it differently, it's ok to first |
24 |
| -implement it for `IOSim` and leave placeholders in the `IOSimPOR` interpreter. |
| 26 | +The `typed-protocols-examples` package contains two simple protocols `PingPong` |
| 27 | +& `ReqResp` which are used for illustration & testing. |
25 | 28 |
|
26 |
| -If you are adding a new functionality to `MonadSTM`, don't forget to support it |
27 |
| -in `strict-stm` package. |
| 29 | +``` |
| 30 | +cabal run typed-protocols-examples:test |
| 31 | +``` |
| 32 | + |
| 33 | +# Code Style |
| 34 | + |
| 35 | +Please follow local style. For a more detailed style guide see |
| 36 | +[link](https://github.com/input-output-hk/ouroboros-network/blob/master/docs/StyleGuide.md). |
| 37 | + |
| 38 | +# Pull Requests |
| 39 | + |
| 40 | +Each commit shall be small and preferably address one thing at a time. Well |
| 41 | +organised & documented commits make it much easier for the maintainers to |
| 42 | +review them. |
28 | 43 |
|
29 |
| -Please also include your changes in `CHANGELOG.md` file. |
| 44 | +New features should be well documented & tested, which means including new |
| 45 | +tests as necessary. You might be asked by the maintainers to write & include |
| 46 | +additional tests. |
30 | 47 |
|
| 48 | +Each commit should build & test, at least the package you are changing. You |
| 49 | +can update other packages from this repository in a subsequent commit. |
31 | 50 |
|
32 |
| -[style-guide]: https://github.com/input-output-hk/ouroboros-network/blob/master/docs/StyleGuide.md |
| 51 | +Please use a draft PRs if the work is still in progress. |
| 52 | + |
| 53 | +We require all commits to be signed, see [this guide][gh-signing-commits]. |
| 54 | + |
| 55 | +If your pull requests resolves an existing issue, please link your PR to that |
| 56 | +issue, see [GitHub documentation][gh-link-issue]. |
| 57 | + |
| 58 | +Please include your changes in `CHANGELOG.md` files (per package). |
| 59 | + |
| 60 | +## MonadSTM features |
| 61 | + |
| 62 | +If you are adding a new functionality to `MonadSTM`, don't forget to support it |
| 63 | +in `strict-stm` package. |
33 | 64 |
|
| 65 | +[CHaP]: https://github.com/input-output-hk/cardano-haskell-packages/ |
| 66 | +[gh-link-issue]: https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue |
| 67 | +[gh-signing-commits]: https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits |
0 commit comments