# Contribution Guidelines

## Reporting Issues

Please [open an issue](https://gitlab.com/morley-framework/morley/issues/new)
if you find a bug or have a feature request.
Before submitting a bug report or feature request, check to make sure it hasn't already been submitted.

The more detailed your report is, the faster it can be resolved.
Please use issue templates to create an issue.

## Code

If you would like to contribute code to fix a bug, add a new feature, or
otherwise improve our project, merge requests are most welcome.

Our merge request template contains a [checklist](/.gitlab/merge_request_templates/default.md#white_check_mark-checklist-for-your-merge-request) of acceptance criteria for your merge request.
Please read it before you start contributing and make sure your contributions adhere to this checklist.

### Prelude

All Haskell code uses
[Universum](https://hackage.haskell.org/package/universum) as a
replacement for the default prelude.

### Tests

We use [`tasty`](https://hackage.haskell.org/package/tasty) as our primary top-level testing framework.
Some old code may use `hspec` instead, but all new code must use `tasty`.
We use [`tasty-discover`](https://hackage.haskell.org/package/tasty-discover) to automatically find all tests.
We still require explicit exports to ensure that we don't accidentally miss some test.
If we accidentally name some test in a way which will be ignored by `tasty-discover`, `weeder` will detect a useless export.

Some hints regarding `tasty` and our test-suite:
1. You can use `--hide-successes` to see only failing tests.
It's useful because otherwise if test suite fails you need to find the cause of failure manually.
2. However, beware of [this issue](https://github.com/feuerbach/tasty/issues/152) with `--hide-successes`.
In short, this option is somewhat broken when `tasty` thinks that it outputs to console.
A workaround is to set `TERM=dumb`.
3. You can run tests using our `Makefile`, see below.

## Cabal and Stack

We use [`hpack`](https://hackage.haskell.org/package/hpack) and `stack.yaml` to maintain the project
and its dependencies, but we also provide `.cabal` files in the repository due to
[stack issue](https://github.com/commercialhaskell/stack/issues/4906) which makes it impossible
to use `morley` as a dependency with stack version > 2 without `.cabal` files. Also we provide
`cabal.project` and `cabal.project.freeze` files in order to provide an ability to build the
project using `cabal`. If you want to update dependencies in one of these cabal related files you
should transfer changes to `package.yaml` or `stack.yaml` and run [`scripts/generate-cabal-files.sh`](scripts/generate-cabal-files.sh),
this script will update these files.

## Makefile

We have a [Makefile](/Makefile) which provides shortcuts for the most
common developers' activities, like building with flags suitable for
development, testing, applying `stylish-haskell` and `hlint`, building
Haddock documentation. Mentioned `Makefile` builds morley itself,
each extra package, like [`morley-ledgers`](/morley-ledgers/Makefile),
has its own `Makefile`.

If you want to run test suite with additional options, set `TEST_ARGUMENTS` variable.
Example: `TEST_ARGUMENTS="--pattern Parser" make test`.
If you want to enable `--hide-successes` option, you can use `make test-hide-successes`.
It will automatically set `TERM=dumb` which is a workaround for the issue mentioned earlier.

## Branching policy

Our branching policy is described [here](/docs/branching.md).

## Build recomendations

### Emacs intero

As soon as this repository uses different default extensions in different packages,
Intero may report non-existing errors.
This issue is known (once located under https://github.com/chrisdone/intero/issues/554)
and will never be resolved unless `intero` project is resurrected.

However, with proper care, this problem can be avoided. Just follow the rules:
* When working with `morley` package, select only `morley:*` packages in `intero-targets`.
* When developing on Lorentz within e. g. `morley-ledgers` package, make sure that
you first built morley core with `make morley`, only after that open the Lorentz modules.
Then set `morley-ledgers:*` packages as intero targets.