Skip to content

Commit 1120f39

Browse files
committed
CONTRIBUTING.md
Use similar CONTRIBUTING.md guide to one for `typed-protocols`.
1 parent e0069c8 commit 1120f39

File tree

1 file changed

+52
-18
lines changed

1 file changed

+52
-18
lines changed

CONTRIBUTING.md

Lines changed: 52 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,67 @@
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
28

39
We designed `io-classes` to be as close as possible to what `base` package
410
provides. Almost all `IO` instances instantiate with api provided by one of
511
the core packages, see
612
[example](https://github.com/input-output-hk/io-sim/blob/main/io-classes/src/Control/Monad/Class/MonadSTM.hs?plain=1#L410-L446).
713
Please keep this in mind when adding new functionality.
814

9-
## Style Guide
15+
# Using in your project
1016

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.
1223

13-
## Pull Request
24+
# Testing
1425

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.
2528

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.
2843

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.
3047

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.
3150

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.
3364

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

Comments
 (0)